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CHAPTER 1 


Getting Around in the Networking 
Services Library 


Networking is pervasive in this digital age in which we live. Information at your fingertips, 
distributed computing, name resolution, and indeed the entire Internet—the advent 

of which will be ascribed to our generation for centuries to come—imply and require 
networking. Everything that has become the buzz of our business and personal lives, 
including e-mail, cell phones, and Web surfing, is enabled by the fact that networking 
has been brought to the masses (and we’ve barely scraped the beginning of the trend). 
You, the network-enabled Windows application developer, need to know how to lasso 
this all-important networking services capability and make it a part of your application. 
You've come to the right place. 


Networking isn’t magic, but it can seem that way to those who aren’t accustomed to 

it (or to the programmer who isn’t familiar with the technologies or doesn’t know how to 
make networking part of his or her application). That’s why the Networking Services 
Developer’s Reference Library isn’t just a collection of programmatic reference 
information; it would be only half-complete if it were. Instead, the Networking Services 
Library is a collection of explanatory and reference information that combine to provide 
you with the complete set that you need to create today’s network-enabled Windows 
application. | 


The Networking Services Library is the comprehensive reference guide to network- 
enabled application development. This library, like all libraries in the Windows 
Programming Reference Series (WPRS), is designed to deliver the most complete, 
authoritative, and accessible reference information available on a given subject of 
Windows network programming—without sacrificing focus. Each book in each library is 
dedicated to a logical group of technologies or development concerns; this approach has 
been taken specifically to enable you to find the information you need quickly, emcledty, | 
and intuitively. 


In addition to its networking services development information, the Networking Services 
Library contains tips designed to make your programming life easier. For example, 

a thorough explanation and detailed tour of MSDN Online is included, as is a section 
that helps you get the most out of your MSDN subscription. Just in case you don’t have 
an MSDN subscription, or don’t know why you should, I’ve included information about 
that too, including the differences between the three levels of MSDN subscription, what 
each level offers, and why you’d want a subscription when MSDN Online is available 
over the Internet. | 
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To ensure that you don’t get lost in all the information provided in the Networking 
Services Library, each volume’s appendixes provide an all-encompassing programming 
directory to help you easily find the particular programming element you’re looking for. 
This directory suite, which covers all the functions, structures, enumerations, and other 
programming elements found in network-enabled application development, gets you 
quickly to the volume and page you need, saving you hours of time and bucketsful 

of frustration. 


How the Networking Services Library Is Structured 


The Networking Services Library consists of five volumes, each of which focuses on 
a particular aspect of network programming. These programming reference volumes 
have been divided into the following: 


e Volume 1: Winsock and QOS 

e Volume 2: Network Interfaces and Protocols 
° Volume 3: RPC and WNet 

e Volume 4: Remote Access Services 

e Volume 5: Routing 


Dividing the Networking Services Library into these categories enables you to quickly 
identify the Networking Services volume you need, based on your task, and facilitates 
your maintenance of focus for that task. This approach enables you to keep one 
reference book open and handy, or tucked under your arm while researching that aspect 
of Windows programming on sandy beaches, without risking back problems (from toting 
around all 3,000+ pages of the Networking Services Library) and without having to 
shuffle among multiple less-focused books. 


Within the Networking Services Library—and in fact, in all WPRS Libraries—each 
volume has a deliberate structure. This per-volume structure has been created to further 
focus the reference material in a developer-friendly manner, to maintain consistency 
within each volume and each Library throughout the series, and to enable you to easily 
gather the information you need. To that end, each volume in the Networking Services 
Library contains the following parts: 


e Part 1: Introduction and Overview 
e Part 2: Guides, Examples, and Programmatic Reference 
e Part 3: Intelligently Structured Indexes 
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Part 1 provides an introduction to the Networking Services Library and to the WPRS 
(what you’re reading now), and a handful of chapters designed to help you get the most 
out of networking technologies, MSDN, and MSDN Online. MSDN and WPRS Libraries 
are your tools in the developer process; knowing how to use them to their fullest will 
enable you to be more efficient and effective (both of which are generally desirable 
traits). In certain volumes (where appropriate), I’ve also provided additional information 
that you'll need in your network-enabled development efforts, and included such 
information as concluding chapters in Part 1. For example, Volume 3 includes a chapter 
that explains terms used throughout the RPC development documentation; by putting 

it into Chapter 5 of that volume, you always know where to go when you have a question 
about an RPC term. Some of the other volumes in the Networking Services Library 
conclude their Part 1 with chapters that include information crucial to their volume’s 
contents, but I’ve been very selective about including such information. Publishing 
constraints have limited the amount of information | can provide in each volume 

(and in the library as a whole), so I’ve focused on the priority: getting you the most 
useful information possible within the number of pages | have to work with. 


Part 2 contains the networking reference material particular to its volume. You'll notice 
that each volume contains much more than simple collections of function and structure 
definitions. A comprehensive reference resource should include information about how 
to use a particular technology, as well as definitions of programming elements. 
Consequently, the information in Part 2 combines complete programming element 
definitions with instructional and explanatory material for each programming area. 


Part 3 is a collection of intelligently arranged and created indexes. One of the biggest - 
Challenges of the IT professional is finding information in the sea of available resources 

and network programming is probably one of the most complex and involved of any 

development discipline. In order to help you get a handle on network programming 

references (and Microsoft technologies in general), Part 3 puts all such information into 

an understandable, manageable directory (in the form of indexes) that enables you 

to quickly find the information you need. 


How the Networking Services Library Is Designed 


The Networking Services Library (and all libraries in the WPRS) is designed to deliver 
the most pertinent information in the most accessible way possible. The Networking | 
Services Library is also designed to integrate seamlessly with MSDN and MSDN Online 
by providing a look and feel consistent with their electronic means of disseminating 
Microsoft reference information. In other words, the way a given function reference 
appears on the pages of this book has been designed specifically to emulate the way 
that MSDN and MSDN Online present their function reference pages. 


_ The reason for maintaining such integration is simple: to make it easy for you to use the 
tools and get the ongoing information you need to create quality programs. Providing a 
“common interface” among reference resources allows your familiarity with the 
Networking Services Library reference material to be immediately applied to MSDN or 
MSDN Online, and vice-versa. In a word, it means consistency. 
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You'll find this philosophy of consistency and simplicity applied throughout WPRS 
publications. I’ve designed the series to go hand-in-hand with MSDN and MSDN Online 


_ resources. Such consistency lets you leverage your familiarity with electronic reference 


material, then apply that familiarity to enable you to get away from your computer if you’d 
like, take a book with you, and—in the absence of keyboards and e-mail and upright 
chairs—get your programming reading and research done. Of course, each of the 
Networking Services Library volumes fits nicely right next to your mouse pad as well, 
even when opened to a particular reference page. 


With any job, the simpler and more consistent your tools are, the more time you can 


spend doing work rather than figuring out how to use your tools. The structure and 


design of the Networking Services Library provide you with a comprehensive, 
presharpened toolset to build compelling Windows applications. 


CHAPTER 2 


What’s In This Volume? 


Volume 1 of the Networking Services Developer’s Reference Library focuses on what 
many developers think of first when network programming comes to mind: Winsock. 
Quality of Service (QOS) is implemented through calls to Winsock functions, so it only 
makes sense to keep these two technologies together in one volume—enabling you to 
read about a given Winsock function when learning about QOS, then to flip back to the 
Winsock section and get the details on that particular Winsock function. If you’ve read 
through the first chapter in any of the WPRS Libraries (including this one), you'll know 
that my primary objective is to ensure that these volumes provide you with the 

_ information you need in as convenient and useful a way as possible. Keeping QOS with 
Winsock (in the same volume) is one way I’ve tried to achieve that objective in this 
library. I've also structured other volumes in this library with similar goals toward 
cohesiveness and cross-technology referencing. | : 


This volume also has information about how you can use development resources 

such as MSDN, MSDN Online, and other developer support resources. This helpful 
_information is found in various chapters in Part 1, and those chapters are common to all 

WPRS volumes. By including this. information | in each library and in each volume, a few 

goals of the WPRS are achieved: | 


° | don't presume you have bought or expect you to have to buy another WPRS Library 
to get access to this information. Maybe your primary focus is network programming, 
and your budget doesn’t allow for you to purchase the Active Directory Developer's 
Reference Library. Since I’ve included this information in this library, you don’t have. 
to. | | | | 


e You can access this important and useful information regardless of which volume you 
have in your hand. You don’t have to (nor should you have to) fumble with another 
physical book to refer to information about how to get the most out of MSDN, or where 
to get support for questions you have about a particular Windows development 
problem you're having. 


e Each volume becomes more useful, more portable, and more complete in and 
Of itself. This goal of the WPRS makes it easier for you to grab one of its libraries’ 
volumes and take it with you, rather than feeling like you must bring multiple volumes 
with you to have access to the library’s important overview and usability information. 


These goals have steered this library’s content and choices of included technologies; 
| hope you find its information is useful, portable, a good value, and as accessible 
as it can be. 
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Part 2 of this volume is broken into two sections: 


¢ Windows Sockets 2 
e Quality of Service (QOS) 


This distinction between Windows Sockets 2 (Winsock 2) and QOS is achieved by the 
focus of the chapters, rather than the introduction of additional partitioning (such as 
dividing it into Part 2 and Part 3). This ensures consistency throughout the volumes 

in this library and in WPRS libraries in general. I’ve ensured that the chapter names 
clearly identify whether the contents focus on Winsock or QOS. 


Winsock 


The first collection of chapters i in Part 2 describes Windows Sockets 2 (Winsock) and 
enables application programmers to create advanced Internet, intranet, and other 
network-capable applications that transmit application data across the wire, independent 
of the network protocol being used. With Winsock, application programmers are provided 
access to advanced Windows networking capabilities such as multicast and QOS. Since 
Windows Sockets 2 is a continuation of the previous Windows Sockets programming 
standard, Windows Sockets 2 applications have the added feature of backward 


| _ compatibility with Windows Sockets 1.1 applications. 


Windows Sockets 2 uses the sockets paradigm that was first popularized by Berkeley 


_ Software Distribution (BSD) UNIX. It was later adapted for Microsoft Windows 


in Windows Sockets 1.1. 


Because Windows Sockets 2 is an interface and not a protocol, it is eapable | 
of discovering and utilizing the communications capabilities of any number of 


| underlying transport protocols. 


The first chapters in Part 2 provide a complete treatment of the following: 


e Windows Sockets API 
e Windows Sockets SPI 


e Windows Sockets Annex 


Chapter 2 What's In This Volume? 


Quality of Service 


QOS is an industry-wide initiative to enable more efficient use of the network. The IETF 
has provided many documents in the form of Internet Drafts and RFCs that outline such 
capabilities, including those provided by the Intserv, Diffserv, ISSLL, and RAP IETF 
working groups, among others. The goal of QOS is to provide preferential treatment 

to certain subsets of data, enabling such data to traverse the traditionally best-effort 
Internet or intranet with higher quality transmission service. 


QOS in Microsoft Windows 2000 is a collection of components that enable such 
differentiation, preferential treatment, and management of higher quality data 
transmissions across the network. The collection of QOS components included 

in Windows 2000 constitutes the Microsoft Corporation implementation of the IETF 
vision of QOS. ae: : 


The collection of QOS chapters in this volume covers the following information: 
e QOS Overview 
e Programming QOS 
e QOS Functions 
e Traffic Control (TC) Reference 
e Local Policy Module (LPM) Reference 
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CHAPTER 38 


Using Microsoft Reference 
Resources 


Keeping current with all the latest information on the latest networking technology is like 
trying to count the packets going through routers at the MAE-WEST Internet service 
exchange by watching their blinking activity lights: It's impossible. Often times, 
application developers feel like those routers might feel at a given day’s peak activity; too 
much information is passing through them, none of which is being absorbed or passed 
along fast enough for their boss’ liking. 


For developers, sifting through all the available information to get to the required 
information is often a major undertaking, and can impose a significant amount of | 
overhead upon a given project. What’s needed is either a collection of information that 
has been sifted for you, shaking out the information you need the most and putting that 
pertinent information into a format that’s useful and efficient, or direction on how to sift 
the information yourself. The Networking Services Developer’s Reference Library does 
the former, and this chapter and the next provide you with the latter. 


This veritable white noise of information hasn’t always been a problem for network 
programmers. Not long ago, getting the information you needed was a challenge 
because there wasn’t enough of it; you had to find out where such information might be 
located and then actually get access to that location, because it wasn’t at your fingertips 
or on some globally available backbone, and such searching took time. In short, the 
availability of information was limited. 


Today, the volume of information that surrounds us sometimes numbs us; we’re 
overloaded with too much information, and if we don’t take measures to filter out what 
we don't need to meet our goals, soon we become inundated and unable to discern 
what’s “white noise” and what’s information that we need to stay on top of our respective 
fields. In short, the overload of available information makes it more difficult for us to find 
what we really need, and wading through the deluge slows us down. 


This fact applies equally to Microsoft’s reference material, because there is so much | 
information that finding what you need can be as challenging as figuring out what to do 
with it once you have it. Developers need a way to cut through what isn’t pertinent to 
them and to get what they’re looking for. One way to ensure you can get to the 
information you need is to understand the tools you use; carpenters know how to use 

- nail-guns, and it makes them more efficient. Bankers know how to use ten-keys, and it 
makes them more adept. If you’re a developer of Windows applications, two tools you 
should know are MSDN and MSDN Online. The third tool for developers—reference 
books from the WPRS—can help you get the most out of the first two. 
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Books in the WPRS, such as those found in the Networking Services Developer's 
Reference Library, provide reference material that focuses on a given area of Windows 
programming. MSDN and MSDN Online, in comparison, contain all of the reference 
material that all Microsoft programming technologies have amassed over the past few 
years, and create one large repository of information. Regardless of how well such 
information is organized, there’s a lot of it, and if you don’t know your way around, 
finding what you need (even though it’s in there, somewhere) can be frustrating, time- 
consuming, and just an overall bad experience. 


This chapter will give you the insight and tips you need to navigate MSDN and MSDN 
Online and enable you to use each of them to the fullest of their capabilities. Also, other 
Microsoft reference resources are investigated, and by the end of the chapter, you'll 
know where to go for the Microsoft reference information you need (and how to quickly 
and efficiently get there). 


The Microsoft Developer Network 


MSDN stands for Microsoft Developer Network, and its intent is to provide developers 
with a network of information to enable the development of Windows applications. Many 
people have either worked with MSDN or have heard of it, and quite a few have one of 
the three available subscription levels to MSDN, but there are many, many more who 
don’t have subscriptions and could use some concise direction on what MSDN can do 
for a developer or development group. If you fall into any of these categories, this _ 
section is for you. 


There is some clarification to be done with MSDN and its offerings; if you’ve heard of 
MSDN, or have had experience with MSDN Online, you may have asked yourself one of 
these questions during the process of getting up to speed with either resource: 


e Why do | need a subscription to MSDN if resources such as MSDN Online are 
accessible for free over the Internet? 


e What is the difference between the three levels of MSDN subscriptions? 


e Is there a difference between MSDN and MSDN Online, other than the fact that one is 
on the Internet and the other is on a CD? Do their features overlap, separate, 
coincide, or what? - 


If you have asked any of these questions, then lurking somewhere in the back of your 
thoughts has probably been a sneaking suspicion that maybe you aren’t getting the most 
out of MSDN. Maybe you’re wondering whether you’re paying too much for too little, or 
not enough to get the resources you need. Regardless, you want to be in the know and 
not in the dark. By the end of this chapter, you'll know the answers to all these questions 
and more, along with some effective tips and hints on how to make the most effective 
use of MSDN and MSDN Online. : 
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Comparing MSDN with MSDN Online 


Part of the challenge of differentiating between MSDN and MSDN Online comes with 
determining which has the features you need. Confounding this differentiation is the fact 
that both have some content in common, yet each offers content unavailable with the 
other. But can their difference be boiled down? Yes, if broad strokes and some 
generalities are used: 


e MSDN provides reference content and the latest Microsoft product software, all 
shipped to its subscribers on CD or DVD. 


e MSDN Online provides reference content and a development community forum, and 
is available only over the Internet. 


Each delivery mechanism for the content that Microsoft is making available to Windows 
developers is appropriate for the medium, and each plays on the strength of the medium 
to provide its “customers” with the best possible presentation of material. These 
strengths and medium considerations enable MSDN and MSDN Online to provide 
developers with different feature sets, each of which has its advantages. 


MSDN is perhaps less “immediate” than MSDN Online because it gets to its subscribers 
in the form of CDs or DVDs that come in the mail. However, MSDN can sit in your 
CD/DVD drive (or on your hard drive), and isn’t subject to Internet speeds or failures. 
Also, MSDN has a software download feature that enables subscribers to automatically 
update their local MSDN content over the Internet, as soon as it becomes available, 
without having to wait for the update CD/DVD to come in the mail. The interface with 

_which MSDN displays its material—which looks a whole lot like a specialized browser 

~ window—is also linked to the Internet as a browser-like window. To further coordinate 

MSDN with the immediacy of the Internet, MSDN Online has a section of the site 
dedicated to MSDN subscribers that enable subscription material to be updated (on their 
local machines) as soon as it’s available. 


MSDN Online has lots of editorial and technical columns that are published directly to 
_the site, and are tailored (not surprisingly) to the issues and challenges faced by 
developers of Windows applications or Windows-based Web sites. MSDN Online also 
has a customizable interface (somewhat similar to MSN.com) that enables visitors to 
tailor the information that’s presented upon visiting the site to the areas of Windows 
development in which they are most interested. However, MSDN Online, while full of 
up-to-date reference material and extensive online developer community content, 
doesn’t come with Microsoft product software, and doesn’t reside on your local machine. 


Because it’s easy to confuse the differences and similarities between MSDN and MSDN 
Online, it makes sense to figure out a way to quickly identify how and where they depart. 
_ Figure 3-1 puts the differences—and similarities—between MSDN and MSDN Online 
_ into a quickly identifiable format. | | 
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MSDN Online, and vice-versa. 
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Remember, too, that if you are an MSDN subscriber, you can still use MSDN Online and 
its features. So it isn’t an “either/or” question with regard to whether you need an MSDN 
subscription or whether you should use MSDN Online; if you have an MSDN 
subscription, you will probably continue to use MSDN Online and the additional features 
provided with your MSDN subscription. 


MSDN Subscriptions 


lf you’re wondering whether you might benefit from a subscription to MSDN, but you 
aren’t quite sure what the differences between its subscription levels are, you aren’t 
alone. This section aims to provide a quick guide to the differences in subscription levels, 
and even provides an estimate for what each subscription level costs. 


The three subscription levels for MSDN are: Library, Professional, and Universal. Each 
has a different set of features. Each progressive level encompasses the lower level’s 
features, and includes additional features. In other words, with the Professional 
subscription, you get everything provided in the Library subscription plus additional 
features; with the Universal subscription, you get everything provided in the Professional 
subscription plus even more features. 


MSDN Library Subscription 


The MSDN Library subscription is the basic MSDN subscription. While the Library 
subscription doesn’t come with the Microsoft product software that the Professional and 
Universal subscriptions provide, it does come with other features that developers may 
find necessary in their development effort. With the Library subscription, you get the 
following: 


e The Microsoft reference library, including SDK and DDK documentation, updated 
quarterly 

e Lots of sample code, which you can cut-and-paste into your projects, royalty free 

e The complete Microsoft Knowledge Base—the collection of bugs and workarounds 

e Technology specifications for Microsoft technologies 


io e The complete set of product documentation, such as Microsoft Visual Studio, - 
Microsoft Office, and others 


e Complete (and in some cases, partial) electronic copies of selected books and 
magazines _ 


e Conference and seminar papers—if you weren't there, you ¢ can use » MSDN s notes 


In addition to these items, you also get: 


e Archives of MSDN Online columns 

e Periodic e-mails from Microsoft chock full of aavelaoment: related information 
e A subscription to MSDN News, a bi-monthly newspaper from the MSDN folks 
e Access to subscriber-exclusive areas and material on MSDN Online 
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MSDN Professional Subscription 


The MSDN Professional subscription is a superset of the Library subscription. In addition 
to the features outlined i in the previous section, MSDN Professional subscribers get the 
following: 


e Complete set of Windows operating systems, including release versions of 
Windows 95, Windows 98, and Windows NT 4 Server and Workstation. 

e Windows SDKs and DDKs in their entirety 

e International versions of Windows operating systems (as chosen) 

e Priority technical support for two incidents in a development and test environment 


MSDN Universal Subscription 


The MSDN Universal subscription is the all-encompassing version of the MSDN 
subscription. In addition to everything provided in the Professional subscription, 
Universal subscribers get the following: 


e The latest version of Visual Studio, Enterprise Edition 


e The Microsoft BackOffice test platform, which includes all sorts of Microsoft product 
software incorporated in the BackOffice family, each with a special 10- connection 
license for use in the development of your software products 


e Additional development tools, such as Office Developer, Microsoft FrontPage, and 
_ Microsoft Project 


e Priority technical support for two additional incidents in a development and test 


environment (for a total of four incidents) 


Purchasing an MSDN Subscription © 


Of course, all the features that you get with MSDN subscriptions aren’t free. MSDN 
subscriptions are one-year subscriptions, which are current as of this writing. Just as 
each MSDN subscription escalates in functionality of incorporation of features, so does 
each escalate in price. Please note that prices are subject to change. 


The MSDN Library subscription has a retail price of $199, but if you’re renewing an 
existing subscription you get a $100 rebate in the box. There are other perks for existing 


_ Microsoft customers, but those vary. Check out the Web site for more details. 


The MSDN Professional subscription is a bit more expensive than the Library, with a 
retail price of $699. If you’re an existing customer renewing your subscription, you again 
get a break in the box, this time in the amount of a $200 rebate. You also get that break 


_ ifyou’re an existing Library subscriber who's upgrading to a Professional subscription. 


The MSDN Universal subscription takes a big jump in price, sitting at $2,499. If you’re 


_ upgrading from the Professional subscription, the price drops to $1,999, and if you’re 


upgrading from the Library subscription level, there’s an in-the-box rebate for $200. 
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As is often the case, there are academic and volume discounts available from various 
resellers, including Microsoft, so those who are in school or in the corporate environment 
can use their status (as learner or learned) to get a better deal—and in most cases, the 
deal is in fact much better. Also, if your organization is using lots of Microsoft products, 
whether or not MSDN is a part of that group, ask your purchasing department to look into — 
the Microsoft Open License program; the Open License program gives purchasing 
breaks for customers who buy lots of products. Check out www. microsoft.com/licensing 
for more details. Who knows, if your organization qualifies you could end up getting an 
engraved pen from your purchasing department, or if you’re really lucky maybe even a 
plaque of some sort for saving your company thousands of dollars on Microsoft products. 


You can get MSDN subscriptions from a number of sources, including online sites 
specializing in computer-related information, such as www.iseminger.com (shameless 
self-promotion, | know), or from your favorite online software site. Note that not all 
software resellers carry MSDN subscriptions; you might have to hunt around to find one. 

_ Of course, if you have a local software reseller that you frequent, you can check out 
whether they carry MSDN subscriptions. 


As an added bonus for owners of this Networking Services Developer’s Reference 
Library, in the back of Volume 1, you'll find a $200 rebate good toward the purchase of 
an MSDN Universal subscription. For those of you doing the math, that means you 
actually make money when you purchase the Networking Services Developer's 
Reference Library and an MSDN Universal subscription. With this rebate, every 
developer in your organization can have the Networking Services Developer’s Refence 
Library on their desk and the MSDN Universal subscription on thier desktop, and still 
come out $50 ahead. That’s the kind of math even accountants can like. 


‘Using MSDN 


MSDN subscriptions come with an installable ntertaics, and the Professional and 

Universal subscriptions also come with a bunch of Microsoft product software such as 

Windows platform versions and BackOffice applications. There’s no need to tell you how 

to use Microsoft product software, but there’s a lot to be said for providing some quick 

but useful guidance on getting the most out of the interface to present and navigate 

through the seemingly endless supply of reference material provided with any MSDN 
subscription. | 


~ To those who have used MSDN, the interface shown in Figure 3. 21s likely familiar It's 
the navigational front- end to MSDN reference material. | a 


| The interface is familiar and straightforward enough, But if you don’t have a grasp on its 
features and navigation tools, you can be left a little lost in its sea of information. With a 
few sentences of explanation and some tips for effective z hawigation, however, you can 
increase its effectiveness dramatically. 3 , 
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Navigating MSDN 

One of the primary features of MSDN—and to many, its primary drawback—is the sheer 
volume of information it contains, over 1.1GB and growing. The creators of MSDN likely 
realized this, though, and have taken steps to assuage the problem. Most of those steps 
relate to enabling developers to ee navigate through MSDN’s content. 


4 MSDN Library - October 1999 
anus : a 


MSDN Library - 
October 1999 


TEEMSOM Library - October 1999 


@- Welcome to the MSDN Library 
@: Visual Studio 6.0 Documentation Welcome to the October 1999 


@: Office Developer Documentation release of the MSDN Library. 

@: ‘Windows CE Documentation 

@ Platform SDK || The MSDN Library is the essential reference for developers, with 
@ SDK Documentation ||) more than a gigabyte of technical programming information, 

@ DDK Documentation 1] including sample code, documentation, technical articles, the 

i @ windows Resource Kits |_| Microsoft Developer Knowledge Base, and anything else you 


@ Tools and Technologies might need to develop solutions that implement Microsoft 
@ Knowledge Base 
; technology. 

@ Technical Articles 

@ Backgrounders 

Bo Specifications 

& Books | pr. cur's Espresso Stand 

ff) @® Partial Books 

i @® Periodicals Dr. GUI introduces the October 1999 release of the MSDN Library. The 

ff @& Samples good doctor examines new Library content, including articles and 
documentation about Windows 2000, Windows CE, Office 2000, and 
databases and data access, plus several new technical article sample 
suites, 


"What's New on the Library 


Read through this document for summaries of what's new and follow 
the links to the new titles. 


Figure 3-2: The MSDN interface. 


Basic navigation through MSDN is simple and is a lot like navigating through Microsoft 
Windows Explorer and its folder structure. Instead of folders, MSDN has books into 
which it organizes its topics; expand a book by clicking the + box to its left, and its 
contents are displayed with its nested books or reference pages, as shown in Figure 3-3. 


If you don’t see the left pane in your MSDN viewer, go to the View menu and select 


Navigation Tabs and they’ ll appear. 


The four tabs in the left pane of MSDN—increasingly referred to as property sheets 
these days—are the primary means of navigating through MSDN content. These four 
tabs, in coordination with the Active Subset drop-down box above the four tabs, are the 
tools you use to search through MSDN content. When used to their full extent, these 
coordinated navigation tools greatly improve your MSDN experience. — 
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((Entire Collection) 


MADCAP 


#] M DN ibrary - October 1999 
fH @ Welcome to the MSDN Library 
ie & Visual Studio 6.0 Documentation Purpose |. General 
i i informati 

S Office Developer Documentation MADCAP, or Multicast Address ation 
4] @ ‘Windows CE Documentation D : ; about 

~ ynamic Client Allocation 
EI ( Platform SDK Protocol, is a technolo ca 

© Getting Started ; oY 


é aimed at making it easy for 
aa eS Desion Strategies and Standards niente ca rendweand-raleace Reference 
fH @ Base Services 


Multicast addresses, enablin 
@ Component Services . ; 3 Documentation 
clients to dynamically of MADCAP 
© Data Access Services " u eT m . 
. aoe connect" and “disconnect functions and 
f @ Graphics and Multimedia Services fF animultinges network 
@ Management Services structures. 


transmissions. 

eS Messaging and Collaboration Services 
€) (0) Networking and Directory Services The development of Feedback 
 @ Active Directory, ADSI, and Directory Services standards for MADCAP is 


© Common Internet File System Protocol ongoing, and falls under the 
@ Fax Service Multicast Address Allocation reports and 


1 @ Intemet Protocol Helper {malloc} Working Group at the Lette 
i & Lightweight Directory Access Protocol (LDAP]A IETF. directly to 
a O Microsoft SNA Server 


Microsoft, 
ast Address > Cinamic Chent Allacation Fra Where Applicable 
i Naver Management 


Overview 


Make error 


Developers can use MADCAP 
ta: 


Figure 3-3: Basic navigation through MSDN. 


The Active Subset drop-down box is a filter mechanism; choose the subset of MSDN 
information you’re interested in working with from the drop-down box, and the 
information in each of the four Navigation Tabs (including the Contents tab) limits the 
information it displays to the information contained in the selected subset. This means 
that any searches you do in the Search tab, and in the index presented in the Index tab, 
are filtered by their results and/or matches to the subset you define, greatly narrowing 
the number of potential results for a given inquiry. This enables you to better find the 
information you’re really looking for. In the Index tab, results that might match your 
inquiry but aren't in the subset you have chosen are grayed out (but still selectable). In 
the Search tab, they simply aren’t displayed. 


MSDN comes with the following predefined subsets (these subsets are subject to 
change, based on documentation updates and TOC reorganizations): 


Entire Collection | Platform SDK, Networking Services 

MSDN, Books and periodicals: | Platform SDK, Security 

MSDN, Content on Disk 2 only | Platform SDK, Tools and Languages 
(CD only — not in DVD version) _ Platform SDK, User Interface Services 

MSDN, Content on Disk 3 only Platform SDK, Web Services | 
(CD only — not in DVD version) Platform SDK, Win32 API 

MSDN, Knowledge Base : . Repository 2.0 Documentation 

MSDN, Technical Articles and: ~ Visual Basic Documentation 


Backgrounders - | a Visual C++ Documentation 
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Office Developer Documentation | Visual C++, Platform SDK and 

Platform SDK, BackOffice WinCE Docs 

Platform SDK, Base Services Visual C++, Platform SDK, and 

Platform SDK, Component Services Enterprise Docs 

Platform SDK, Data Access Services Visual FoxPro Documentation 

Platform SDK, Getting Started Visual InterDev Documentation 

Platform SDK, Graphics and Visual J++ Documentation 
Multimedia Services Visual SourceSafe Documentation 

Platform SDK, Management Services Visual Studio Product Documentation 

Platform SDK, Messaging and Windows CE Documentation 


Collaboration Services 


As you can see, these filtering options essentially mirror the structure of information 
delivery used by MSDN. But what if you are interested in viewing the information in a 
handful of these subsets? For example, what if you want to search on a certain keyword 
through the Platform SDK’s ADSI, Networking Services, and Management Services 
subsets, as well as a little section that’s nested way into the Base Services subset? 
Simple—you define your own subset by choosing the View menu, and then selecting the 
Define Subsets menu item. You’re presented with the window shown in Figure 3-4. 


Defining a subset is easy; just take the following steps: 


1. Choose the information you want in the new subset; you can choose entire subsets or 
selected books/content within available subsets. 


2. Add your selected information to the subset you’re creating by clicking the Add button. 


3. Name the newly created subset by typing in a name in the Save New Subset As box. 
Note that defined subsets (including any you create) are arranged in alphabetical 
order. 


You can also delete entire subsets from the MSDN installation. Simply select the subset 
you want to delete from the Select Subset To Display drop-down box, and then click the 
nearby Delete button. | 


Once you have defined a subset, it becomes available in MSDN just like the predefined 
subsets, and filters the information available in the four Navigation Tabs, just like the 
predefined subsets do. 


Quick Tips - 
Now that you know how to navigate MSDN, there are a sak: of tips and tricks that you 
can use to make MSDN as effective as it can be. 


Use the Locate button to get your bearings. Perhaps it’s human nature to need to 
know where you are in the grand scheme of things, but regardless, it can be bothersome | 
to have a reference page displayed in the right pane (perhaps jumped to from a search), 
without the Contents tab in the left pane being synchronized in terms of the reference 
page’s location in the information tree. Even if you know the general technology in which 
your reference page resides, it’s nice to find out where it is in the content structure. 
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This is easy to fix. Simply click the Locate button in the navigation toolbar and all will be 
synchronized. 


Define 


& 


: ee — oe S 

MSON Library - October 1999 -_ — (awson Library - October 1999 
@BwWelcometothe MSDN Libay == LA Pato SDK 
& Visual Studio 6.0 Documentation a bee _ . : Liyy Networking and Directory Services 
@ Oifice Developer Documentation = | | 18) Platform SDK 
@ Windows CE Documentation ee inde ‘kets: Platform SD 
CC) Platform SDK : 

No Getting Started 


a Design Strategies and Standards 
Base Services 
Component Services 
Data Access Services 


Figure 3-4: The Define Subsets window. 


Use the Back button just like a browser. The Back button in the navigation toolbar 
functions just like a browser's Back button; if you need information on a reference page 
you viewed previously, you can use the Back button to get there, rather than going 
through the process of doing another search. 


Define your own subsets, and use them. Like | said at the beginning of this chapter, 
the volume of information available these days can sometimes make it difficult to get our 
work done. By defining subsets of MSDN that are tailored to the work you do, you can 
become more efficient. | : 


Use an underscore at the beginning of your named subsets. Subsets in the Active 
Subset drop-down box are arranged in alphabetical order, and the drop-down box shows 
only a few subsets at a time (making it difficult to get a grip on available subsets, | think). 
Underscores come before letters in alphabetical order, so if you use an underscore on all 
of your defined subsets, you get them placed at the front of the Active Subset listing of 
available subsets. Also, by using an underscore, you can immediately see which subsets 
you’ve defined, and which ones come with MSDN—it saves a few seconds at most, but 
those seconds can add up. | 
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Using MSDN Online 


MSDN underwent a redesign in December of 1999, aimed at streamlining the 
information provided, jazzing things up with more color, highlighting hot new 
technologies, and various other improvements. Despite its visual overhaul, MSDN Online 
still shares a lot of content and information delivery similarities with MSDN, and those 
similarities are by design; when you can go from one developer resource to another and 
immediately work with its content, your job is made easier. However, MSDN Online is 
different enough that it merits explaining in its own right—it’s a different delivery medium, 
and can take advantage of the Internet in ways that MSDN simply cannot. 


If you’ve used MSN’s home page before (www.msn.com), you’re familiar with the fact 
that you can customize the page to your liking; choose from an assortment of available 
national news, computer news, local news, local weather, stock quotes, and other 
collections of information or news that suit your tastes or interests. You can even insert a 
few Web links and have them readily accessible when you visit the site. The MSDN 
Online home page can be customized in a similar way, but its collection of headlines, 
information, and news sources are all about development. The information you choose 
specifies the information you see when you go to the MSDN Online home page, just like 
the MSN home page. 


There are a couple of ways to get to the customization page; you can go to the MSDN 
Online home page (msdn.microsoft.com) and click the Personalize This Site button near 
the top of the page, or you can go there directly by pointing your browser to 
msdn.microsoft.com/msdn- A aie However you get there, the page you'll 
see is shown in Figure 3-5. 


As you can see from Figure 3-5, there are lots of technologies to choose from (many 
more options can be found when you scroll down through available technologies). If 
you’re interested in Web development, you can select the checkbox at the left of the 
page next to Standard Web Development, and a predefined subset of Web-centered 
technologies is selected. For technologies centered more on Network Services, you can 
go through and choose the appropriate technologies. If you want to choose all the 
technologies in a given technology group more quickly, click the Select All button in the 
technology’s shaded title area. 


You can also choose which tab is selected by default in the home page that MSDN 
Online presents to you, which is convenient for dropping you into the category of MSDN 


Online information that interests you most. All five of the tabs available on MSDN 


Online’s home page are available for selection; those tabs are the following: 


e Features 

e News 

e Columns 
Technical Articles 
Training & Events 
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Personalize your Start page - Microsoft Internet Explorer 


Preset Templates 


Select or clear the check boxes 


below to choose a pre-set PersonaliZe the information that appears on your MSDN Online home page. 
template of information for that . 
technology Select your preferences fram the sections below, then return here and choose Save. (Yes, we 


know it's a lot of choices. There's a lot of information on this site.) You can update your choices 


Database at any time by visiting this Personalization page. 


Development/Administration 


Database Web Developrnent 
Office“ VBA Developer 


Standard Web Development : 
» Components (General Info} 2: Activex Controls 
Component Object Model (COM) .— COM+ (Component Services) 
. DCOM | Design-Time Controls 
Co Message Queuing (MSMQ) Microsoft Transaction Server (MTS) 
OLE | Server components 


Windows Development 


| Databases (General Info} ADO 
»DAO Data Binding 
‘Data transformation ! English Query 


Figure 3-5: The MSDN Online Personalize Page. 


Once you've defined your profile—that is, customized the MSDN Online content you 
want to see—MSDN Online shows you the most recent information pertinent to your 
profile when you go to MSDN Online’s home page, with the default tab you’ve chosen 
displayed upon loading of the MSDN Online home page. | 


Finally, if you want your profile to be available to you regardless of which computer 
you're using, you can direct MSDN Online to store your profile. Storing a profile for 
MSDN Online results in your profile being stored on MSDN Online’s server, much like 
roaming profiles in Windows 2000, and thereby makes your profile available to you 
regardless of the computer you’re using. The option of storing your profile is available 
when you customize your MSDN Online home page (and can be done any time 
thereafter). The storing of a profile, however, requires that you become a registered 
member of MSDN Online. More information about becoming a registered MSDN Online 
user is provided in the section titled MSDN Online Registered Users. 
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Navigating MSDN Online | 

Once you’re done customizing the MSDN Online home page to get the information 
you’re most interested in, navigating through MSDN Online is easy. A banner that sits 
just below the MSDN Online logo functions as a navigation bar, with drop-down menus 
that can take you to the available areas on MSDN Online, as Figure 3-6 illustrates. 


SDN Online - ft Internet Explore 


essential resources for develo pers 


, Key Tapics 


| ; Windows 2000 
) What's New in XML for Microsoft | ML 
Windows 2000 

MSDN Subscriptions Learn about the new features, bug fixes, and other 
MSDN Training : improvements to the Microsoft XML parser coming in 
Products Windows 2000, in this column by Charlie Heinemann af 
the Microsoft XML tearn. Charlie also explains why the 
G Partnering new version of the parser is better equipped for server 
International use, (Deo 21, Colurnn} | 
My Links 


IT Professionals 


Visual Studia 


DLL Help 
Database 


© Technical Article 


> MSDN Flash 
(e-newsletter) 


Send Us Tune in to the MSDN Show 
Your Feedback Learn about new technologies coming out of Microsoft in MSDN Online's 
% Site Guide _ first streaming media show. This show's topics include XML and BizTalk. 


iOeo 15, Strearnicm: video 


introducing the New MSDN Oniine 


Figure 3-6: The MSDN Online Navigation Bar with Its Drop-Down Menus. 


Following i is a list of available menu categories, which groups’ the available sites and 
features within MSDN Online: 


Home | | | Resources 
Magazines : | ~ Downloads 
Libraries Wee | Search MSDN 


Developer Centers 


The navigation bar is available regardless of where you are in MSDN Online, so the 
capability to navigate the site from this familiar menu is always available, leaving you a 
click away from any area on MSDN Online. These menu categories create a functional 
and logical grouping of MSDN Online’s feature offerings. 
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MSDN Online Features 


Each of MSDN Online’s seven feature categories contains various sites that comprise 
the features available to developers visiting MSDN Online. 


Home is already familiar; clicking on Home in the navigation bar takes you to the MSDN 
Online home page that you’ve (perhaps) customized, showing you all the latest 
information about technologies that you’ve indicated you're interested in reading about. 


Magazines is a collection of columns and articles that comprise MSDN Online’s 
magazine section, as well as online versions of Microsoft’s magazines such as MSu, 
MIND, and the MSDN Show (a Webcast feature introduced with the December 1999 
remodeling of MSDN Online). The Magazines feature of MSDN Online can be linked to. 
directly at msdn.microsoft.com/resources/magazines.asp. The Magazines home page is 
shown in Figure 3-7. 


MSDN Online Magazines - Microsoft Inter 


ie] http: //medn. microsoft. com/resources/magazines. asp 


All Products 


vor’ * Magazines 


— MIND 
MSOM Newspaper 
MSDH Show 


~ Print and online publications for current information on all types of development. 


Microsatt Systems Journal (MS 73 
MS? is the magazine that brings developers monthly features on the most important tools and 


technologies such as *ML, Windows 2000, ATL, MFC, Windows CE, DirectX, C++, a5 well as rnonthly 
columns on visual programming, Win 32, COM, debugging, security, and more. 


Micrasoft Internet Developer {MIND} 

MIND is the monthly magazine for Internet and intranet developers that covers toals and technologies 
including XML, Visual Basic, scripting, ADO, SQL Server, IIS, and anything else a developer might need 
to build an interactive or e-commerce site. 


MSDN News 


The MSOM News is a printed newspaper, published bi- -moanthly for the developer audience. The 
newspaper features new technical articles and ongoing columns, including the popular "Ask Dr, GUI," as 
Well as 4 regular series of posters. Subscriptions are free to MSDN subscribers. 


The MSDN Show 
This regular Webcast brings you inside Microsoft to talk with developers and planners about our hottest 
new technologies. The segments range from broad overviews to down-and-dirty coding, with some 

— news and entertainment mixed in, too. 


Figure 3-7: The Magazines Home Page. 


For those of you familiar with the Voices feature : section that formerly found its home on 
the MSDN Online navigation banner, don’t worry; all content formerly in the Voices 
section is included the Magazines section as a subsite (or menu item, if you prefer) of 
the Magazines site. For those of you who aren’t familiar with the Voices subsite, you'll 
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find a bunch of different articles or “voices” there, each of which adds its own particular 
twist on the issues that face developers. Both application and Web developers can get 
their fill of magazine-like articles from the sizable list of different articles available (and 
frequently refreshed) in the Voices subsite. With the combination of columns and online 
developer magazines offered in the Magazines section, you’re sure to find Pony of 


interesting insights. 


Libraries is where the reference material available on MSDN Online lives. The Libraries 
site is divided into two sections: Library and Web Workshop. This distinction divides the 
reference material between Windows application develooment and Web development. 
Choosing Library from the Libraries menu takes you to a page through which you can 
navigate in traditional MSDN fashion, and gain access to traditional MSDN reference 
material. The Library home page can be linked to directly at msdn.microsoft.com/library. 
Choosing Web Workshop takes you to a site that enables you to navigate the Web 
Workshop in a slightly different way, starting with a bulleted list of start points, as shown 
in Figure 3-8. The Web Workshop home page can be linked to directly at 
msdn.microsoft.com/workshop. | 


MSDN Online Web Workshop - Microsoft Internet Explorer. 


http: //msdn. microsoft. com/workshop/ 


ESSENTIALS 

Companent Development 

Cortent & Component Ceslivery 

Data Access & Databases 

Design 

DHTML, HTML & CSS 

Languages & Development Tools 
Me ssaging & Collaboratian 


Networking, Protecals 
& Data Formats 


Reusing Browser Technology 
Security & Cryptography 
Server Technologies 
Streaming & Interactive Media 
Web Content Management 


MML CExtensible Markup Language) 


Figure 3-8: 


® 


& 


Component 
Development 


This section contains 
information you'll need ta 
create components for your 
Web pages, using either 
Activex or DHTML scriptlet 
technology, as well as related 
information about COM, 
ActiveX Scripting, Active 
Documents, and offline 
browsing. 


pprort | arch | 


Welcome 


The MSDN Online Web 
Workshop provides the latest 
information about Internet 
technologies, including 
reference material and in- 
depth articles on all aspects 
of Web site design and 
development. Choose the 
categories on the left to 
navigate via content listings. 
Use the index to look up 
keywords, and the search 
page for specific queries. 
Check our What's New page 
for updates. 


The MSON Online team 


© 1999 Microsoft Corporation, All rights reserved, Terms of use, 


The Web Workshop Home Page. 


Pobre 
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Developer Centers is a hub from which developers who are interested in a particular 
area of develooment—such as Windows 2000, SQL Server, or XML—can go to find 
focused Web site centers within MSDN Online. Each developer center is dedicated to 
providing all sorts of information associated with its area of focus. For example, the 
Windows 2000 developer center has information about what’s new with Windows 2000, 
including newsgroups, specifications, chats, knowledge base articles, and news, among 
others. At publication time, MSDN Online had the following developer centers: 


e Microsoft Windows 2000 
e Microsoft Exchange 

e Microsoft SQL Server 

¢ Microsoft Windows Media 
e XML 


In addition to these developer centers is a promise that new centers would be added to 
the site in the future. To get to the Developer Centers home page directly, link to 
msdn.microsoft.com/resources/devcenters.asp. Figure 3-9 shows the Developer Centers 
home page. 


MSDN Developer Centers - Microsoft Internet Explorer 


All Products Sipepeork ‘softcam Guide 


Deusen ts MSDN Developer Centers 


Microsoft Exchange MSDN Developer Centers provide access to all the developer resources MSDN has to offer for specific 
Microsoft SOL Server products and technologies. From the Developer Centers you can also find the latest links to all the best 
Hicacom windows ~ new technical articles, downloads, samples, product news, and more. While we'll be adding more 
Media Developer Centers to the site in the future, you can visit the following Developer Centers today: 


on Mioresott Windows 20! 
Microsoft Exchange 
Microsoft SOL Server 
Microsoft Windows Media 
AML 


Figure 3-9: The Developer Centers Home Page. 
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Resources is a place where developers can go to take advantage of the online forum of 
Windows and Web developers, in which ideas or techniques can be shared, advice can 
be found or given (through MHM, or Members Helping Members), and the MSDN User 
Group Program can be joined or perused to find a forum to voice their opinions or chat 
with other developers. The Resources site is full of all sorts of useful stuff, including 
featured books, a DLL help database, online chats, case studies, and more. The 
Resources home page can be linked to directly at msdn.microsoft.com/resources. Figure 
3-10 provides a look at the Resources home page. | 


icrosof net Explorer 


medn online All Products | Support | Search 


PLL Help Database * Additional MSDN Online Resources 
MSDN Online Support « 


HMewsgroups * 


MSON Online is about more than just technical articles and docurnentation. Check out the wide variety 
of resources we offer to help you get your job done. 


Peer Journal # 


Members Helping « - 


Warmer The DLL Help Database 


MSON User Group « Microsoft's DLL Help database provides a searchable database of information about file versions that 
Program ship with a selected set of Microsoft products. 
MSDN Online Chats « 


MSDN Training « MSDN Online Support 
Events * MSDN Online Support offers a large variety of technical resources, including the Microsoft Knowledge 


Developer Books ® Base; service packs, hotfixes, and tools; and Support Web Casts, live presentations by Support 
professionals. 


Newsgroups 


4 MSDN Online provides access to selected developer-focused public newsgroups through our browser- 
a based newsreader, Microsoft's public newsgroups allow you to interact with the Microsoft developer 
community and MVPs (Most Valuable Professionals). Public newsgroups are a great way to solve 
technical problems, learn more about a specific product or technology, or keep up with the latest buzz 
in the developer community. Microsoft employees do not monitor Microsoft's public newsgroups. 


Peer Journal 


Microsoft's collection of code, tips, and articles written by your developer peers. 


Figure 3-10: The Resources Home Page. 


~The Downloads site is where developers can find all sorts of useable items fit to be 
downloaded, such as tools, samples, images, and sounds. The Downloads site is also 
where MSDN subscribers go to get their subscription content updated over the Internet 
to the latest and greatest releases, as described previously in this chapter in the Using 
MSDN section. The Downloads home page can be linked to directly at 

_ msdn.microsoft.com/downloads. The Downloads home page is shown in Figure 3-11. 


Chapter 3 Using Microsoft Reference Resources 27 


‘MSDN Online Downloads - rosoft Internet Explorer 
eee a 


se 


Service Packs * Welcome to the MSDN Online Downloads Area 


Samples « 


TT s 
cols * Service Packs 


Beta and Preview ¢ . : : . 
Releases Service Packs and product updates provide bug fixes and address other issues that customers have 


Images * discovered since 4 product's release. 


“Sounds « 

Software Cevelopment « Samples 

Kits (SDKs) In this section, you will find a great variety of samples that demonstrate ways to use the latest and 

MSDN Subscriber * | greatest Microsoft technologies to make your applications the best they can be. All samples have code 
Downloads that can be downloaded, most can be browsed online, and many have live demonstration pages. 

Choose from the Table of Contents to find samples focused on a particular product or technology. 

Entries prefixed with g¢ are for users registered with Visual Studio only. To get access to these, register 


your product today. 


Tools 


Want to try out some great new products? Check out our tools area, where users can download more 
than 40 trial, beta, and full versions of the latest developer products. 


Visit the Visual Studio Solutions Center for sample solutions designed to help you learn and understand 
end-to-end application architecture and design. 


Beta and Preview Releases 


Figure 3-11: The Downloads Home Page. 


The Search MSDN site on MSDN Online has been improved over previous versions, 
and includes the capability to restrict searches to either library (Library or Web — 
Workshop), as well as other fine-tune search capabilities. The Search MSDN home page 
can be linked to directly at msdn.microsoft.com/search. The Search MSDN home page is 
shown in Figure 3-12. 


There are two other destinations within MSDN Online of specific interest, neither of 
which is immediately reachable through the MSDN navigation bar. The first is the MSDN 
Online Member Community home page, and the other is the Site Guide. 
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Choosing this aption will allow you to search the developer topics in the Microsoft Knowledge Base. 
Or you can go toa the Support area for an advanced Knowledge Base Search. 


Figure 3-12: The Search MSDN Home Page. 


The MSDN Online Member Community home page can be directly reached at 
msdn.microsoft.com/community. Many of the features found in the Resources 
navigation menu are actually subsites of the Community page. Of course, becoming a 
member of the MSDN Online member community requires that you register (see the next 
section for more details on joining), but doing so enables you to get access to Online 
Special Interest Groups (OSIGs) and other features reserved for registered members. 
The Community page is shown in Figure 3-13. 


Another destination of interest on MSDN Online that isn’t displayed on the navigation 
banner is the Site Guide. The Site Guide is just what its name suggests—a guide to the 
MSDN Online site that aims at helping developers find items of interest, and includes 
links to other pages on MSDN Online such as a recently posted files listing, site maps, 
glossaries, and other useful links. The Site Guide home page can be linked to directly at 
msdn.microsoft.com/siteguide. 
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Welcome to the MSDN Online Member Community 
Join* Updated October 14, 1999 


Your Membership . 
OSIGs With an MSDN Online membership, developers can easily access technical 


information, tools, and a camrmnunity of developers ready to help solve the 


Peer Journal 
toughest challenges. Join mow and take advantage of member benefits. 


Case Studies 


Downloads F 7 
Online Special-Interest Groups 
Mernbers Helping + 


Marnbers Access the information you need, when you need it, with Online Special-interest 
Srouos (COSIGs), Web-based access to relevant newsgroups, sorted by product, 
make it easy for you to get information you need to do your job. Take advantage 
of special offers, find useful links, and stay up to date with the latest product and 
technology news. 


Training 
MSDM Stores 


Members Helping Members 


Mernbers Heloing Members (MHM) is a networking sad support tool that helps 
developers get connected, salve problems, and gain recognition within the © 
developer community. Get answers quickly by searching the MHM database for 
people who can answer your technical questions. Or, register as a volunteer and 
help other Seve Cpele when they need it, Sign up raw! 


Roaming Profiles 


Sign up for an MSDN Online membership, and we will save your customized — 


Figure 3-13: The MSDN Online Member Community Home Page. 


MSDN Online Registered Users 

You may have noticed that some features of MSDN Online—such as the capability to 
create a store profile of the entry ticket to some community features—require you to 
become a registered user. Unlike MSDN subscriptions, becoming a registered user of 
MSDN Online won't cost you anything more but a few minutes of registration time. 


Some features of MSDN Online require registration before you can take advantage of 
their offerings. For example, becoming a member of an OSIG requires registration. That 
feature alone is enough to register; rather than attempting to call your developer buddy 
for an answer to a question (only to find out that she’s on vacation for two days, and your 
deadline is in a few hours), you can go to MSDN Online’s Community site and ferret 
through your OSIG to find the answer in a handful of clicks. Who knows; maybe your 
developer buddy will begin calling you with questions—you don’t have to tell her where 
you're getting all your answers. 
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There are a number of advantages to being a registered user, such as the choice to 
receive newsletters right in your inbox if you want to. You can also get all sorts of other 
timely information, such as chat reminders that let you know when experts on a given 
subject will be chatting in the MSDN Online Community site. You can also sign up to get 
newsletters based on your membership in various OSIGs—again, only if you want to. It’s 
easy for me to suggest that you become a registered user for MSDN Online—l’m a 
registered user, and it’s a great resource. 7 


The Windows Programming Reference Series 


The WPRS provides developers with timely, concise, and focused material on a given 
topic, enabling developers to get their work done as efficiently as possible. In addition to 
providing reference material for Microsoft technologies, each Library in the WPRS also 
includes material that helps developers get the most out of its technologies, and 
provides insights that might otherwise be difficult to find. 


The WPRS currently includes the following libraries: 


e Microsoft Win32 Developer's Reference Library 
e Active Directory Developer’s Reference Library 
e Networking Services Developer’s Reference Library 


In the near future (subject, of course, to technology release schedules, demand, and 
other forces that can impact publication decisions), you can look for these prospective 
WPRS Libraries that cover the following material: 


e Web Technologies Library 

e Web Reference Library 

e MFC Developer’s Reference Library 
e Com Developer's Reference Library 


What else might you find in the future? Planned topics such as a Security Library, 
Programming Languages Reference Library, BackOffice Developer’s Reference Library, 
_or other pertinent topics that developers using Microsoft products need in order to get 

the most out of their development efforts, are prime subjects for future membership in 

the WPRS. If you have feedback you want to provide on such libraries, or on the WPRS 

In general, you can send email to winprs @ microsoft.com. 


if you're sending mail about a particular library, make sure you put the name of the 
library in the subject line. For example, e-mail about the Networking Services 
Developer's Reference Library would have a subject line that reads “Networking 
Services Developer’s Reference Library.” There aren’t any guarantees that you'll get a 
reply, but I’ll read all of the mail and do what | can to ensure your comments, concerns, 
or (especially) compliments get to the right place. 
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CHAPTER 4 


Finding the Developer Resources 
You Need 


Networking is complex, and its resource information vast. With all the resources 
available for developers of network-enabled applications, and the answers they can 
provide to questions or problems that developers face every day, finding the developer 
information you need can be a challenge. To address that problem, this chapter is 

designed to be your one-stop resource to find the developer resources you need, 
making the job of actually developing your application just a little easier. — 


Microsoft provides plenty of resource material through MSDN and MSDN Online, and the 
WPRS provides a great filtered version of focused reference material and development | 
knowledge. However, there is a lot more information to be had. Some of that information 
comes from Microsoft, some of it from the general development community, and yet 
more information comes from companies that specialize in such development services. 
Regardless of which resource you choose, in this chapter you can find out what your 
development resource options are, and be more informed about the resources that are 
available to you. | | | | 


Microsoft provides developer resources through a number of different media, channels, 
and approaches. The extensiveness of Microsoft’s resource offerings mirrors the fact 
that many are appropriate under various circumstances. For example, you wouldn't go to 
a conference to find the answer to a specific development problem in your programming 
project; instead, you might use one of the other Microsoft resources. | 


Developer Support 


Microsoft's support sites cover a wide variety of support issues and approaches, 
including all of Microsoft’s products, but most of those sites are not pertinent to 
developers. Some sites, however, are designed for developer support; the Product 
Services Support page for developers is a good central place to find the support 
information you need. Figure 4-1 shows the Product Services Support page for. 
developers, which can be reached at www.microsoft.com/support/customer/develop.htm. 


Note that there are a number of options for support from Microsoft, including everything 
from simple online searches of known bugs in the Knowledge Base to hands-on — 
- consulting support from Microsoft Consulting Services, and everything in between. 
The Web page displayed in Figure 4-1 is a good starting point from which you can 
find out more information about Microsoft's support services. __ | 


32 


Volume 1 Winsock and QOS 


arch | microsoft. 


Whether you are a Software or Web Developer, developing or porting 
commercial applications to run on Microsoft platforms requires a unique 
level of support to ensure those applications optimize both current and 
emerging technologies. Microsoft provides access to a wide range of 
product and application development expertise to help developers 
accelerate the development cycle and produce successful applications, 
This includes the Microsoft Developer Network (MSDN™) - a specially 

~ dedicated Web site packed with news, resources and technical services. 


Go to Support Phone Numbers Click here 


PREMIER SUPPORT FOR DE¥YELOPERS 

For large organizations developing products using Microsoft technologies 
who require 4 direct, proactive and managed support relationship with 
Microsoft, Premier Support offers comprehensive and flexible high-end 
support, 


(B) click here for detail 
7, i¢ ere ror details 


PROFESSIONAL SUPPORT FOR DEVELOPERS 
Professional Support for Developers provides information services and 
incident- based support to help create and enhance your software 


Figure 4-1: The Product Services Support page for developers. 


Premier Support from Microsoft provides extensive support for developers, and 
includes different packages geared toward specific Microsoft customer needs. The 
packages of Premier Support that Microsoft provides are: 

e Premier Support for Enterprises 

e Premier Support for Developers 

e Premier Support for Microsoft Certified Solution Providers 
e Premier Support for OEMs 


If you’re a developer, you could fall into any of these categories. To find out more 
information about Microsoft’s Premier Support, contact them at (800) 936-2000. 


Priority Annual Support from Microsoft is geared toward developers or organizations 
that have more than an occasional need to call Microsoft with support questions and 
need priority handling of their support questions or issues. There are three packages 
of Priority Annual Support offered by Microsoft. 
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e Priority Comprehensive Support 
e Priority Developer Support 
e Priority Desktop Support 


The best support option for you as a developer is the Priority Developer support. To 
obtain more information about Priority Developer Support, call Microsoft at 
(800) 936-3500. 


Microsoft also offers a Pay-Per-Incident Support option so you can get help if there’s just 
one question that you must have answered. With Pay-Per-Incident Support, you call a toll- 
free number and provide your Visa, MasterCard, or American Express account number, 
after which you receive support for your incident. In loose terms, an incident is a problem 
or issue that can’t be broken down into subissues or subproblems (that is, it can’t be 
broken down into smaller pieces). The number to call for ag voce Support 

is (800) 936-5800. 


Note that Microsoft provides two priority technical support incidents as part of the MSDN — 
Professional subscription, and provides four priority technical support incidents as part 
of the MSDN Universal subscription. | 


You can also submit questions to Microsoft engineers through Microsoft's support Web 
site, but if you’re on a time line you might want to rethink this approach and consider 
going to MSDN Online and looking into the Community site for help with your 
development question. To submit a question to Microsoft engineers online, 

go to support.microsotft. com/support/webresponse. asp. 


Online Resources 


Microsoft also provides extensive developer support through its community of 

_ developers found on MSDN Online. At MSDN Online’s Community site, you will find 
OSIGs that cover all sorts of issues in an online, ongoing fashion. To get to MSDN 
Online’s Community site, simply go to msdn.microsoft.com/community. _ 


Microsoft's MSDN Online also provides its Knowledge Base online, which is part of the 
Personal Support Center on Microsoft's corporate site. You can search the Knowledge 
Base online at support.microsoft. com/support/search. 


Microsoft provides a number of newsgroups that developers can use to view 
information on newsgroup-specific topics, providing yet another developer resource for 
information about creating Windows applications. To find out which newsgroups are 
available and how to get to them, go to support.microsoftt. com/support/news. 


- The following newsgroups will probably be of particular interest to readers of the 
_ Microsoft Active Directory Developer’s Reference Library: 

microsoft.public.win2000.* 

microsoft.public.msdn.general 

microsoft. public. platformsdk.active. Geno 

microsoft. public. platformsdk.adsi 
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microsoft. public. platformsdk.dist_svcs 
microsoft. public. vb. * 

microsoft.public.vc.* 

microsoft. public. vstudio. “microsoft. poner cert.” * 
microsoft. public.certification. * 


Of course, Microsoft isn’t the only newsgroup provider on which newsgroups pertaining 
to developing on Windows are hosted. Usenet has all sorts of newsgroups—too many to 
list—that host ongoing discussions pertaining to developing applications on the Windows 
platform. You can access newsgroups on Windows development just as you access any 
other newsgroup; generally, you'll need to contact your ISP to find out the name of the 
mail server and then use a newsreader application to visit, read, or post to the 

Usenet groups. 


For network developers with a taste for Winsock (and QOS) programming, another site 
of interest is www.stardust.com, which is chock full of up-to-date information about 
Winsock development and other network-related information. There’s other information 
about network programming on the site, so it’s worth a look. 


Internet Standards 


Many of the network protocols and services implemented in Windows platforms conform 
to one or more Internet standards recommendations that have gone through a process 
of review and comments. One especially useful source of information about such 
standards, recommendations, and ongoing comment periods is the Internet Engineering 
Task Force, or IETF. Rather than go into some long-winded (page-eating) explanation | 
of what the IETF is, does, and stands for, let me simply say that this is the place where 
networking protocols and other various Internet-related services are often born, 
scrutinized, recast, commented upon, and although not standardized or implemented, 
recommended in a final form called a request for comment, or RFC, even though it’s 
essentially a standard by the time it gets to RFC stage. 


If you want to get a clear technical picture of a given technology or protocol, or if you’re 
inclined to comment on the creation and subsequent scrutiny of such things, the place 
you should go is www. ietf.org. This site can tell you all you want to know about the 
goings on of the IETF, their (non-profit) mission, their Working Groups, and all the 
information you might ever want about almost anything that has to do we menorRng 
recommendations. 


If you’re curious about a given protocol or networking technology, and want to find an 
unadulterated (albeit technical) version of its explanation, this is a great place to go. 
It's a virtual hangout for the brightest people in networking, and it’s worth a look or two, 
even just for the sake of satisfying curiosity. 
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Learning Products 


Microsoft provides a number of products that enable developers to get versed in 

the particular tasks or tools that they need to achieve their goals (or to finish their tasks). 
One product line that is geared toward developers is called the Mastering series, and its 
products provide comprehensive, well-structured interactive teaening tools for a wide 
variety of development topics. 


The Mastering Series from Microsoft contains interactive tools that group books and CDs 
together so that you can master the topic in question, and there are products available 
based on the type of application you’re developing. To obtain more information about the 
Mastering series of products, or to find out what kind of offerings the Mastering series 
has, check out msdn.microsoft.com/mastering. 


Other learning products are available from other vendors as well, such as other 
publishers, other application providers that create tutorial-type content and applications, 
and companies that issue videos (both taped and broadcast over the Internet) 

_ on specific technologies. For one example of a company that issues technology-based 
instructional or overview videos, take a look at www.compchannel.com. 


Another way of learning about development in a particular language (such as C++, 
FoxPro, or Microsoft Visual Basic), for a particular operating system, or for a particular 
product (such as Microsoft SQL Server or Microsoft Commerce Server) is to read the © 
preparation materials available for certification as a Microsoft Certified Solutions 
Developer (MCSD). Before you get defensive about not having enough time to get 
certified, or not having any interest in getting your certification (maybe you do—there are 
benefits, you know), let me just state that the point of the journey is not necessarily to 
arrive. In other words, you don’t have to get your certification for the preparation 
materials to be useful; in fact, the materials might teach you things that you thought you 

_ knew well but actually didn’t know as well as you thought you did. The fact of the matter 
is that the coursework and the requirements to get through the certification process are 
rigorous, difficult, and quite detail-oriented. If you have what it takes to get your 
certification, you have an extremely strong grasp of the fundamentals (and then some) of 
application programming and the developer-centric information about Windows. 
platforms. 


_You are required to pass a set of core exams to get an MCSD certification, and then 
you must choose one topic from many available electives exams to complete your 
certification requirements. Core exams are chosen from among a group of available 
exams; you must pass a total of three exams to complete the core requirements. There 
are “tracks” that candidates generally choose which point their certification in a given 

direction, such as C++ development or Visual Basic development. The core exams and 

their exam numbers (at the time of publication) are as follows. 
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Desktop Applications Development (one required): | 

e Designing and Implementing Desktop Applications with Visual C++ 6.0 (70-016) 

e Designing and Implementing Desktop Applications with Visual FoxPro 6.0 (70-156) 
e Designing and Implementing Desktop Applications with Visual Basic 6.0 (70-176) 


Distributed Applications Development (one required): 


e Designing and Implementing Distributed Applications with Visual C++ 6.0 (70-015) 
e Designing and Implementing Distributed Applications with Visual FoxPro 6.0 (70-155) 
e Designing and Implementing Distributed Applications with Visual Basic 6.0 (70-175) 


Solutions Architecture: 


e Analyzing Requirements and Defining Solution Architectures (70-100) 


Elective exams enable candidates to choose from a number of additional exams 

to complete their MCSD exam requirements. The following MCSD elective exams are 
available: 

e Any Desktop or Distributed exam not used as a core requirement 


e Designing and Implementing Data Warehouses with Microsoft SQL Server 7.0 
(70-019) 


e Developing Applications with ee the Microsoft Foundation Class Library 
(70-024) 


e Implementing OLE in Microsoft Foundation Class Applications (70- 025) — 

e Implementing a Database Design on Microsoft SQL Server 6.5 (70-027) 

e Designing and Implementing Databases with Microsoft SQL Server 7.0 (70-029) 
e Designing and Implementing Web Sites with Microsoft FrontPage 98 (70-055) 


e Designing and Implementing Commerce Solutions with | 
Microsoft Site Server 3.0, Commerce Edition (70-057) 


e Application Development with Microsoft Access for Windows 95 and the 
Microsoft Access Developer’s Toolkit (70-069) 


e Designing and Implementing Solutions with Microsoft Office 2000 and | 
Microsoft Visual Basic for Applications (70-091) 


e Designing and Implementing Database Applications with Microsoft Access 2000 
(70-097) 


—@ Designing and Implementing Collaborative Solutions with Microsoft Outlook 2000 and 
Microsoft Exchange Server 5.5 (70- 105) | 


e Designing and Implementing Web Solutions with Microsoft Visual InterDev 6.0 
(70-152) 


e Developing Applications with Microsoft Visual Basic 5.0 (70-165) 
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The good news is that because there are exams you must pass to become certified, 
there are books and other material out there to teach you how to meet the knowledge 
level necessary to pass the exams. That means those resources are available to you— 
regardless of whether you care about becoming an MCSD. 


The way to leverage this information is to get study materials for one or more of these 
exams and go through the exam preparation material (don’t be fooled by believing that if 
the book is bigger, it must be better, because that certainly isn’t always the case.) Exam 
preparation material is available from such publishers as Microsoft Press, IDG, Sybex, and 
others. Most exam preparation texts also have practice exams that let you assess your 
grasp on the material. You might be surprised how much you learn, even though you may 
have been in the field working on complex projects for some time. 


Exam requirements, as well as the exams themselves, can change over time; more 
electives become available, exams based on previous versions of software are retired, 
and so on. You should check the status of individual exams (Such as whether one of the 
exams listed has been retired) before moving forward with your certification plans. For 
more information about the certification process, or for more information about the 
exams, check out Microsoft's certification web site at www. microsoft.com/train_cert/dev. 


Conferences 


Like any industry, Microsoft and the development industry a as a whole sponsor 
conferences on various topics throughout the year and around the world. There are 
probably more conferences available than any one human could possibly attend and still 
maintain his or her sanity, but often a given conference is geared toward a focused topic, 
so choosing to focus on a particular development topic enables developers to winnow 
the number of conferences that apply to their efforts and interests. 


MSDN itself hosts or sponsors almost one hundred conferences a year igome of them 
are regional, and duplicated in different locations, so these could be considered one 
conference that happens multiple times). Other conferences are held in one central 
location, such as the big one—the Professional Developers Conference (PDC). 
Regardless of which conference you’re looking for, Microsoft has provided a central site 
for event information, enabling users to search the site for conferences, based on many - 
different criteria. To find out what conferences or other events are going on in your area 
of interest of development, go to events.microsoft.com. 


Other Resources 


Other resources are available for developers of Windows applications, some of which 
might be mainstays for one developer and unheard of for another. The list of developer 
resources in this chapter has been geared toward getting you more than started with 

_ finding the developer resources you need; it’s geared toward getting you 100 percent of 
the way, but there are always exceptions. 


38 


Volume 1 | Winsock and QOS 


Perhaps you’re just getting started and you want more hands-on instruction than MSDN 
Online or MCSD preparation materials provide. Where can you go? One option is to 
check out your local college for instructor-led courses. Most community colleges offer 
night classes, and increasingly, community colleges are outfitted with pretty nice 
computer labs that enable you to get hands-on development instruction and experience 
without having to work on a 386/20. 


There are undoubtedly other resources that some » people know about that have been 
useful, or maybe invaluable. If you know of a resource that should be shared, send me 
e-mail at winprs @ microsoft.com, and who knows—maybe someone else will benefit 
from your Knowledge. 


lf you’re sending mail about a particularly useful resource, Sil put “Resources” in the 
subject line. There aren’t any guarantees that you'll get a reply, but I’ll read all of the mail 
and do what I can to ensure that your resource idea gets considered. 
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Writing Great IrDA Applications 
(with Winsock) - 


This chapter provides overview and programming information about infrared technology, 
which is standardized by the Infrared Data Association (IrDA), a non-profit organization 
based in Walnut Creek, California. This chapter discusses how to use IrDA technology 
with Microsoft Windows applications (and therefore, with Winsock). IrDA is becoming 
increasingly popular as the digital revolution takes its networking capabilities into the 
wireless world, so IrDA information seemed especially useful for the Networking 
Services Developer's Reference Library. 


A great resource for all things related to infrared networking technology is www.jirda.org. 
Another great resource for finding out about how Microsoft uses (and exposes) IrDA 
technology can be found at www.microsoft.com/hwdev/intrared. 


What Is an Ad-Hoc Networking-Enabled Application? 


Imagine the following Windows application: two notebook computers are placed beside 
each other. A computer icon appears on both desktops with the name of the peer 

~computer below it. Open one of the icons to display a folder with the contents of the peer 
computer’s desktop. Drag and drop between your desktop and the open folder to move 
files between the two computers. 


Imagine that the only configuration this application required was a checkbox for the user 
to enable or disable it. Imagine that several similar applications could be running at the 
same time without interfering with each other. 7 


Imagine that this application could run on millions of existing notebook computers at 
transfer speeds of up to 4 Mb/s. Imagine that instances of the application, regardless of © 
the speed of the underlying hardware, would work with all other instances at a common 
fastest speed. 


Imagine that the other notebook computer in this example was a digital still camera, a 
handheld personal computer, a data capture device, or an electronic commerce device. 


Asa bonus, assume that the two computers did not need to be cabled together. : 


This application is possible today under Windows 2000, Windows 98, and Windows CE. 
The underlying technology is based on inexpensive, widely available, short-range 
infrared transceivers that adhere to the IrDA standards. IrDA standards also enable 
communications between non-Windows devices and Windows applications; these 
standards are freely available from the IrDA website at www.irda.org. 
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What Is IrDA? 


IrDA is an international organization that creates and promotes interoperable, low cost, 
infrared data interconnection standards that support a walk-up, point-to-point 
user model. 


IrDA is a protocol suite designed to support transmission of data between two devices 
over short-range point-to-point infrared at speeds between 9.6Kbps and 4Mbps. 


IrDA is that small semi-transparent red window that you may have wondered about on 
your notebook computer. 


Over the last three years, the members of the IrDA have been very successful at getting 
IrDA hardware deployed in a large number of new notebook computers. One of the 
reasons for this has been the simplicity and low cost of IrDA hardware. Unfortunately, 
until recently, the hardware has not been available for applications programmers to use 
because of a lack of suitable protocol drivers. 


Microsoft Windows CE 1.0 was the first Windows operating system to provide built-in 
IrDA support. Windows 2000 and Windows 98 now also include support for the same 
IrDA programming APIs that have enabled file sharing applications and games on 
Windows CE. 


IrDA implementations are becoming available on several popular embedded operation 
systems. 


SIR and FIR IrDA hardware can easily be added to a desktop computer by attaching a 
dongle to a serial port (SIR) or by adding a card and a dongle (FIR). In the future, USB- 
attached FIR IrDA devices will be available. 


What Is IrDA-C (Previously Known as IrBus)? 


IrDA-C is a standard from the IrDA organization that is intended to support low speed 


wireless PC peripheral devices such as keyboards and joysticks. IrDA-C is a low speed 


(75 Kb/s shared among several devices), low latency, unreliable, long distance (20 feet), 
wide angle, multiple device protocol. IrDA-C is a PC-peripheral style bus protocol, and is 
not exposed to the application developer. In this chapter, the term “IirDA" refers to the 
IrDA1.1 protocols, which are also known as IrDA-D. _ 


IrDA-C does not interoperate with IrDA-D. The IrDA-C specification includes a 


~ mechanism that could allow IrDA-C and IrDA-D to share hardware, but this mechanism 


is incompatible with the IrDA protocols in Windows 2000 and Windows CE because of 
performance enhancements in these implementations of the IrDA-D protocols. IrDA-C 
and IrDA-D can still exist in the same device, but must be physically separate. 
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What Is Unique about IrDA? 


IrDA is uniquely suited to ad-hoc point-to-point networking: 


IrDA is a great non-cable. Mismatched connectors and wiring are impossible with IrDA. 
Speed and configuration parameters are transparently negotiated at connect time and a 
common set is used for the connection. IrDA at 4 Mb/s is compatible with 9.6 Kb/s IrDA. 
Additionally, the IrDA connector is completely sealed, inexpensive, and available from 
multiple vendors. 


Common user-space APIs. The combination of IrDA and Windows Sockets presents 
the application programmer with a powerful yet simple Win32 user-space API that 
exposes multiple, fully error-corrected data streams. Serial and parallel ports are the only 
other point-to-point technologies that have a commonly available user space API. IrDA 
defines rich functionality that does not exist with serial and parallel cables. IrDA borrows 
from the very successful client/server connection and programming model defined by the 
TCP/IP family of protocols and the Winsock APIs. 


Open protocols support non-Windows devices. Winsock exposes the IrDA TinyTP 
protocol to the application writer. A non-Windows device that implements the TinyTP 
protocol will be able to easily exchange data with Windows applications. 


IrDA and Winsock support the implementation of easy to use, zero configuration, always 
works data eneng eee cen, es -hoc point-to-point networking. © 


DA Core Protocols and Services. 


The core IrDA services are similar to those exposed by the popular TCP protocol. — 
Applications running on two different machines are able to easily open multiple reliable — 
connections between themselves for the purpose of sending and receiving data. Like 
TCP, client applications connect to a server application by specifying a device | 

(TCP hos?) address and an application (TCP port) address. 


Serial IrDA (SIR) Physical Layer (115 Kb/s) 


The SIR specification defines a short-range infrared asynchronous serial transmission 
mode with one start bit, eight data bits and one stop bit. The maximum data rate is 
115.2Kbps (half duplex). The primary benefit of this scheme is that existing serial 
hardware can be used very cheaply. This is one of the reasons for the eae 
any of IrDA. 


Fast IrDA (FIR) Physical ro (4 Mb/s) 


The FIR specification defines short-range low power operation at 4Mpbs ven duplex). 
AIL FIR devices are also required to support SIR operation. 
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IrLAP Data Link Layer 


Data rates are negotiated and changed during IrLAP connection establishment. 
This is completely transparent to the application. 


IrLAP defines two protocols. The first is a discovery protocol that is used directly by an 
application to learn about currently visible devices, their nicknames and device (MAC) 
addresses. Discovery is an area where IrDA differs from other common bus or 
networking protocols. It is not expected that clients have advance knowledge of the 
device addresses of servers—they simply ask for a list of who is visible and then 
select one. 


_ The information returned from a discovery is a list of device MAC addresses, human 


readable device nicknames, and a bitmask of hints that suggest the nature of peer 
devices. MAC addresses are randomly generated 32-bit values. 


The IrLAP data link protocol is based on the widely implemented HDLC data link 
protocol. Ir_AP provides a simple reliable connection between two devices. If the HDLC 
connection is broken for any reason, an error is quickly reported back to applications. 


IrLMP and TinyTP 


The IrLMP and TinyTP layers add multiple session support to IrLAP. In theory, this 
support exists to allow multiple applications to have multiple concurrent connections 
active. While this operation is fully supported, often only one application can be active at 
once. IrLMP and TinyTP still provide significant value in that they allow multiple 
applications to be listening for incoming connections without interfering with each other. 
A single application might also choose to open a control connection and a data 
connection at the same time. This is made possible by the IrLMP and TinyTP layers. 


IrLMP and TinyTP also add per-connection flow control to the flow control provided by 
the single IrLAP connection. This allows an application to offer data in large blocks to the 
IrDA stack and allow the stack to send it at optimal speeds. It is not necessary for the 
application to be concerned about lost data or flow control. 


Winsock exposes the TinyTP service interface to application programs. 


IrLMP includes a directory services protocol, Information Advertising Service (IAS), that 
runs directly on top of IrLMP. IAS is commonly used to map an ASCII service name to a 
LSAP-SEL. LSAP-SEL is a protocol element used to select one from possibly many | 


applications running on the server. The service name is a friendlier abstraction that is 


exposed to applications. Non-Windows devices must be aware of the conventions used 
by Windows. These are described below. 


IrLMP defines a mode of service called exclusive mode. In this mode, only a single 


_ IrLMP connection is supported and the flow control features of IrLAP are used. TinyTP is 


not used. Exclusive mode is used by the IrLPT protocol that talks to IrLPT printers. 
(See Figure 5-1.) 


IrcOM 
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Figure 5-1: Core IrDA Protocols. 


IrCOMM was the most frequently used programming interface for IrDA on Windows 95. 
Windows 98 continues to support IrCOMM, but Winsock is the strategic interface for 
IrDA on all Windows platforms. There are several reasons behind this decision. 


IrCOMM is a family of protocols that run on top of the core IrDA protocol suite. ITrCOMM 
supports the emulation of a peer device connected via a serial or parallel cable. This 
emulation is from the perspective of applications that are accessing serial and parallel 
ports through the operating system API. ae _ 


An IrCOQMM implementation generally takes the form of a system installable serial port 
driver. Rather than talking to real serial hardware, it uses the services exported by the 
core IrDA protocols. | | 


The basic mechanism of IrCOMM serial-connected device emulation is to convert 
RS-232 serial line state change requests generated by one application into protocol 
messages that are communicated to the peer application through the native serial API. 


In the case of modems, some of line state change protocol messages correspond to 
established conventions for relaying state changes on the analog side of the modem 
back to the computer (drop DCD to signal a line carrier drop). Other line state changes 
are used to stop the computer from overrunning buffers in the modem (CTS, RTS). 
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When two systems are connected together via an RS-232 cable (no modems), ad-hoc 
application conventions are used to map line state changes into bi-directional flow 
control and application specific signaling. The Windows 95 Direct Cable Connect feature 
is an example of such an application. | 


The use of line state changes to implement flow control is largely a legacy application to 
application concept. The underlying IrDA protocols fully support flow control between 
systems; even an IrDA modem could dispense with lead state changes and simply use 
the underlying IrDA protocol flow control mechanisms to stop the computer from sending 
more data. 


IrCOMM Modes 


IrCOMM is actually a family of protocols. Only 9 Wire Mode supports the propagation of 
line state change information. The IrLPT protocol is used to talk to printers. 3 Wire Raw 
Mode and IrLPT run the core IrDA stack in exclusive mode, which precludes other 
applications from using the stack at the same time. 3 Wire Cooked Mode uses the 
services of IrLMP and TinyTP, does not preclude other applications from using the stack, 
and does not propagate line state change information. 9 Wire Mode is like 3 Wire 
Cooked Mode but also supports line state change messages. 


In order to achieve ITCCOMM communication, a common mode must be negotiated at 
IrCOMM connection setup time. 


IrCOMM 


IrDA 


Figure 5-2: IrCOMM Internal Architecture. 


The philosophy behind IrCOMM was to support IrDA modems and legacy applications 
built on the serial API. In practice, because the serial API was the most commonly 
available IrDA user space API, new IrDA applications were designed around IrCOMM. 
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IrCOMM runs on top of a reliable protocol layer, but session establishment and release 
services are not exposed through the serial API. Additionally, the underlying IrDA 
connection can be broken and re-established without this information being 
communicated to the application through the serial API. The result of this is that IrCOMM 
is not a reliable protocol in practice, and IrCOMM applications must be prepared to add 
yet anther layer of reliability. 


No IrCOMM Virtual Serial Ports on Windows 2000 


Windows 2000 does not expose IrCOMM virtual serial ports. There are several reasons 
for this. 


Many customers have difficulty with the concept of virtual ports. This is especially 
confusing when the SIR IrDA hardware itself may need to be configured on a real serial 
port, and then the customer must further configure their application to use a virtual 
serial port. 


Multiple applications cannot share a virtual serial port. This is particularly troublesome if, 
for example, an IrCOMM-based application opens the single virtual serial port and holds 
it open until system shutdown. An example of this would be an IrTran-P file transfer 
application running as a background service. No other IrDA application or driver will be 
able to run on that system, even though the underlying IrDA protocols provide support to 
allow multiple applications to be waiting for incoming connections, and allow clients to 
select a target application at connect time through established protocol mechanisms. 


Windows 2000’s support for multiple concurrent adapters and IrDA connections to 
different devices cannot be well supported under an API and protocol that assumes only 
a single device connection. 


_ The complexity and various modes of ITCOMM make real world interoperability a very 
tough problem. 


Windows 2000 Support for IrCOMM Through Winsock 


In order to support certain legacy IrDA devices, including IrTran-P based cameras, ~ 
Windows 2000 implements a subset of the IrCOMM protocol, but exposes this protocol 
through the Winsock API rather than through the serial API. In particular, only 9 Wire 
Mode IrCOMM is supported, and line state change information is not supported. | 
Windows 2000 only advertises that it supports the ITCOMM 9 Wire Mode. Devices must 
be able to initiate the IrDA connection, and not to expect Windows to initiate the 
connection as a side-effect of discovering new devices. IrCOMM through Winsock 
programming details are found later in this chapter. 


The fundamental limitation of the IrCOMM protocol, that you cannot have multiple 
servers listening for incoming connections, is still exposed in this implementation. If one. 
application is listening for incoming IrCOMM connections, another application trying to © 
do so will get an error from Winsock. For this reason it is recommended that all new 

_ applications either avoid IrCCOMM or support multiple mode concurrently. 
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IrDA and the Windows Sockets API 


Good Winsock applications are critical to the easy-to-use, zero-configuration, always- 
works IrDA vision. IrDA and Winsock present a unique opportunity for applications that 
can fill the ever-increasing need for i data Ene: between Windows and non- 
Windows devices. 


Talking to Non-Windows Devices 


The Winsock programming API adds only a basic application-level naming convention 
(supported through IAS) to the IrDA specified protocol suite. A device that implements 
the core IrDA protocol and adheres to the simple naming conventions should be able to 
interoperate easily with Windows. | 


Devices are free to implement the required functionality of a Winsock client or server, or 
both. Client and server refer only to who initiates the connection. Once a connection is 
established, data can be reliably exchanged in both directions. Since server side 
functionality requires slightly more IrDA stack functionality, Windows will often be the 
server. It is up to the application writer to choose the trigger that initiates the IrDA 
connection. The connection can be driven from a user initiated action, or can be the 
result of discovering a device in a discovery polling loop. The application programmer is 
completely unconstrained as to client/server roles and connection establishment. 


Devices that are battery constrained should refrain from continuous polling to drive 
connection initiation. 


Either side can close the connection, although this is generally coordinated by 
application level protocols. A receiver will receive all data that has been sent to Winsock 
by the peer application before it receives notification of the peer connection closure. If 
the connection closes abortively, both sides of the connection will receive an error 
through Winsock. It is always possible to tell the difference between graceful closes and 
abortive closes. 


Well- -designed servers can often support "auile incoming connections concurrently, 
although there is no requirement that simple servers implement this. 


Application Addressing 


Application level addressing is the ability of a client application to request a connection 
to a particular server application (actually to a particular socket, or communications 
endpoint). Multiple server applications can be waiting ea as for incoming 
connections without interfering with one another. 


The actual protocol, IrLMP, directly supports the concept of application level addressing 
_ through an 8-bit protocol field called an LSAP-SEL. 
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Since LSAP-SELs are only 8 bits wide and no authority coordinates this space, using a 
well-known LSAP-SEL to identify an application is not recommended. Windows uses the 
GetValueByClass IAS service to map an ASCII service name to an LSAP-SEL at 
connect time. This means that a server can register itself with an ASCII name, and a 
client can connect to this server by using the same name. 


Non-Windows devices can connect to a Windows server by performing an IAS 
GetValueByClass query on the attribute IrDA: TinyTP:LsapSel with the desired service 
name as the class. The result of this query will be an LSAP-SEL, which the device can 
then use to initiate a TinyTP connection. The correct server will receive the incoming 
connection. The actual LSAP-SELs used in this scheme may change every time a server 
is restarted. 


Non-Windows devices can support an inbound connection from a Windows system by 
supporting the same query initiated by the Windows side. _ 


Figure 5-3: Application Addressing. 


Data T ransfer and Connection Close 


Once a connection is established, Winsock send() and recv() calls translate into TinyTP. 
sends and receives. Even though IrLAP itself is half-duplex, the application is not aware 
of this. Send() and recv() can be called at the same time, on the same connection, on 
two different threads. 


The stack manages TinyTP credits on behalf of the application’ When the peer Stone 
issuing TinyTP credits, the sender will block in the send() call. A non-Windows device is 
required to issue TinyTP credits as it is able to consume new data. Windows will stop - 
issuing credits when the receiver stops calling recv() to consume data. _ 
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A Winsock application can send a large buffer of data on a send() call and the stack will 
segment it as required. Applications will get substantially higher performance if they pass 
in at least 8 kB of data on a single send() call. 


IrDA through Winsock supports the SOCK_STREAM data stream semantics, which 
means that any notion of message boundaries is not preserved. Applications commonly 
add a length field to the head of messages to pass this information to a peer. 


When one side of a connection is closed with the closesocket() call, all data that was 
previously sent will be delivered to the peer. When the peer has consumed all data, the 
next recv() call it issues will return with a length of zero, indicating a normal socket close. 
Any error that prevents data from being sent correctly will result in a Winsock error being 
returned to the application. 


Peer IrDA Device (Client) Protocol Windows 
socket() socket() 
socket fandie socket handle 
bind{ name) 
OK/error 
listen(} 
OkK/serror 
accept(} 
* OK/error 
getsockopt(EN UM...) = 
device fist ne 
conne ct nam a ene eA mam Le Ree en ne 
OK/e ror a —_ “——_ new socket handie 
closesocket() 


4+——_ recy 0 len =O 


—- closesockett) 


Figure 5-4: Winsock/IrDA Protocol Mapping. 
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IrDA and Winsock Reference 


This section explains how common Windows Sockets 2 functions are used when 
working with IrDA development. Note that this section is not a replacement of these 
functions’ programmatic reference information found in Part 2 of this volume; these 
entries merely serve to specifically address IrDA-specific applications of these 
applications. For complete reference information on Windows Sockets 2 functions, 
see Chapter 8. 


WSAStartup 


all the WSAStartup function before making any other IrDA function calls: 


af_irda.h 


This header file must be included by Windows Sockets applications to support IrDA. 
There are several incompatible versions of af_irda.h that have been distributed with 
Windows CE and Windows 95 Ir3.0 DDKs and SDKs. A common af_irda.h that supports 
all three platforms is available with the Windows 2000 IrDA DDK. This file may continue 
to evolve as the APIs of the systems grow closer together. : - 


In order to compile for one of the target platforms, one of the following must be defined: 


socket 


The Windows Sockets socket function is used to create a connection endpoint of type 
SOCKET. This is nothing more than an application anchor for future references to a 
connection. The connection is not yet established. Both clients and servers begin all 
communication by opening a socket: | 
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SOCKADDR_IRDA Structure 


The following SOCKADDR structure is used for AF_IRDA sockets: 


The irdaAddressFamily member is always AF_IRDA. 


Server applications use the irdaServiceName member to specify their well-known 
service name in a bind function call. The irdaDevicelD member is ignored by the server 
application. 


Client applications fill in all members. The irdaDevicelD member is filled in with the 
device address of the device that the client wishes to use a connect function call to 
connect to. This address is returned from a previous discovery operation initiated by a 
getsockopt function call with the IRLMP_ENUMDEVICES option. The 
irdaServiceName member is initialized to the well-known value that the server specified 
in its bind function call. 


It is an error for an IrDA application to issue a connect function call after issuing a 
bind call. | 


bind 
The bind function is used by server applications to register that they wish to receive 


incoming connections that are addressed to a specified service name on the specified 
socket. The bind function associates a server socket with an application level address: 


A Windows Sockets bind function call causes the stack to generate a new local LSAP- 
SEL and to add it to the IAS database associated with the service name supplied in the 
SOCKADDR_IRDA structure. 
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This is the function used to perform a discovery. Before a connection can be 
Windows Sockets getsockopt function call returns a list of all currently visible IrDA 


getsockopt(,, IRLMP_ENUMDEVICES,,) and connect() 


devices. A device address returned from this list is cop 
structure to be used by the connect function call. 
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This structure is used with the IRLMP_IAS_QUERY getsockopt option to query a peer’s 
IAS database: , 3 | 


The following code shows the steps necessary to build a server that listens for incoming 
IrCOMM connections: : 


~ (continued) 
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Windows 2000 IrDA Architecture 


Windows 2000 provides some unique support for IrDA. 


IrDA Hardware Drivers 


SIR UART based serial adapters are supported by the Windows 2000 component 
IrSIR.SYS. IrSIR uses the services of the Windows NT serial driver SERIAL.SYS or a 
SERIAL.SYS-compatible serial driver to communicate with the IrDA hardware. Built-in 
SIR hardware should expose itself through the system BIOS as Plug and Play Id 
PNP0O510 or PNP0O511. : 


FIR IrDA hardware must be exposed as an NDIS4.0 miniport driver. FIR drivers can 
expose as many NDIS adapters as the driver can support. Each adapter is a unique IrDA 
transceiver that can support a unique instance of IrLAP. FIR hardware should have a 
unique Plug and Play ID and have an associated vendor-supplied driver. FIR hardware 
that is also compatible with SIR can also expose an alias Plug and Play ID of PNP0510 
or PNP0511 to allow SIR-only operation using IrSIR. 


IrDA.S¥S 


Figure 5-5: Windows 2000 IrDA Architecture. 
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Windows 2000 Multiple-Adapter Support 


The Windows 2000 IrDA stack supports concurrent operation of several NDIS4.0 
FIR/SIR miniport adapters. This support allows a single server to support multiple 
inbound connections in a way that is transparent to both client and server applications. 


An adapter is defined as the hardware/software needed to support a single IrLAP 
connection. | 


Since IrDA is not a routable protocol, multiple-adapters support is limited to connections 
to a single server by multiple clients. Peer devices cannot talk to each other through 
the server. 


Each adapter and IrLAP instance will have a unique IrDA MAC address (DevicelD). 


Discovery operations are run on every idle adapter in sequence. A global list of 
discovered devices is returned. Cached discovery information is maintained on a 
per-IrLAP instance and returned for each adapter that has a connection active. 


The Windows 2000 IrDA stack maintains a mapping between device address and last 
seen adapter. When a connection is requested to a peer device, the stack routes the | 
connection to the correct adapter. Incoming connections are delivered to a single 
listening transport endpoint. The listening client will not receive any per-adapter 
information. The mapping between the new connection and the adapter is maintained by 
the IrDA stack. | | | 7 | 
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CHAPTER 6 


Winsock 2 API Overview 


Welcome to Windows Sockets 2 


This chapter describes the Windows Sockets 2 Application Programming iinietaes (API). 
It consists, primarily, of information from the Windows Sockets 2 API specification, but 
also includes additional information. The information in this document is not presented in 
exactly the same way as in the epeciicalon . 


Using the Windows Sockets 2 API Document 


This document provides the online material needed to create a Windows Sockets 
application for Microsoft Windows® operating systems, using the Microsoft 
implementation of Windows Sockets 2. It is intended as a igouenee tool and outlines the 
functions in the Windows Sockets API. 7 


You should be familiar with Win32® programming concepts to make the best use of this 
document. Thus, you may want to refer to other references that provide a more 
systematic guide to writing Windows Sockets applications. 


Note This documentation is intended for application developers. If you are developing a 
transport or service provider, see the Service Provider Documentation in Chapters 10 
and 11 of this volume. : 


Overview of Windows Sockets 2 


Windows Sockets 2 uses the sockets paradigm that was first popularized by Berkeley 
Software Distribution (BSD) UNIX. It was later bees for Microsoft Windows in 
Windows Sockets 1.1. 


One of the primary goals of Windows Sockets 2 has been to provide a protocol 
independent interface fully capable of supporting emerging networking capabilities, such 
as real-time multimedia communications. 


Windows Sockets 2 is an interface, not a protocol. As an interface, it is used to discover 
and utilize the communications capabilities of any number of underlying transport 
protocols. Because it is not a protocol, it does not in any way affect the bits on the wire, 
and does not need to be utilized on both ends of a communications link. : 


Windows Sockets programming previously centered around TCP/IP. Some of the 
programming practices that worked with TCP/IP do not work with every protocol. As a 
result, the Windows Sockets 2 API added new functions where necessary to handle 
several protocols. | 
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Windows Sockets 2 has changed its architecture to provide easier access to multiple 
transport protocols. Following the Windows Open System Architecture (WOSA) model, 
Windows Sockets 2 now defines a standard service provider interface (SPI) between the 
application programming interface (API), with its functions exported from WS2_32.dll and 
the protocol stacks. Consequently, Windows Sockets 2 support is not limited to TCP/IP 
protocol stacks as is the case for Windows Sockets 1.1. For more information, see 
Windows Sockets 2 Architecture. 


There are new challenges in developing Windows Sockets 2 applications. When sockets 
only supported TCP/IP, a developer could create an application that supported only two 
socket types: connectionless and connection-oriented. Connectionless protocols used 
SOCK_DGRAM sockets and connection-oriented protocols used SOCK_STREAM 
sockets. Now, these are just two of the many new socket types. Additionally, developers 
can no longer rely on socket type to describe all the essential attributes of a transport 


protocol. 


Windows Sockets 2 Features 


Windows Sockets 2 extends functionality in a number of areas. 


Features 


Access to protocols other 
than TCP/IP 


Overlapped |/O with 
scatter/gather 


Protocol-independent 
name resolution facilities 


Protocol-independent 
multicast and multipoint 


Quality of service (QOS) 


Other frequently requested 
extensions 


Description 


Windows Sockets 2 allows an application to use the 
familiar socket interface to achieve simultaneous access to 
a number of installed transport protocols. 


Windows Sockets 2 incorporates the overlapped paradigm 
for socket I/O and incorporates scatter/gather capabilities 
as well, following the model established in Win32 
environments. 


Windows Sockets 2 includes a standardized set of 
functions for querying and working with the myriad name 
resolution domains that exist today (for example DNS, 
SAP, and X.500). 


Windows Sockets 2 applications discover what type of 
multipoint or multicast capabilities a transport provides and 
use these facilities in a generic manner. 


Window Sockets 2 establishes conventions that 
applications use to negotiate required service levels for 
parameters such as bandwidth and latency. Other QOS- 
related enhancements include mechanisms for network- | 
specific QOS extensions. 


Windows Sockets 2 incorporates shared sockets and 
conditional acceptance; exchange of user data at 
connection setup/teardown time; and protocol-specific 
extension mechanisms. 
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Conventions for New Functions 


Windows Sockets 2, with its expanded scope, takes the socket paradigm beyond the 
Original design. As a result, a number of new functions have been added. These have 
been assigned names that begin with WSA. In all but a few instances, these new 
functions are expanded versions of existing functions from BSD sockets. 


The new functions are described in the reference section of the document, following the 
conventions of the Platform SDK. The new functions are also listed in Summary of New 
Functions. | 


Microsoft Extensions and the Windows Sockets 2 API 


The Windows Sockets 2 specification defines an extension mechanism that exposes 
advanced transport functionality to application programs. For more information, see 
Function Extension Mechanism. 


The following Microsoft- -specific extensions were added to Windows Sockets 1.1. They 
are also available in Windows Sockets 2. 


AcceptEx 
GetAcceptExSockaddrs 
TransmitFile 

~ WSARecvEx 


These functions are not exported from the Ws2_ 32. dil; they are eiported from 
_ Mswsock.dll. 


An application written to use the Microsoft- specific éxtensions to Windows Sockets does 
not run correctly over a Windows Sockets service provider that does not support those 
_ extensions. , 


Socket Handles for Windows Sockets 2 


A socket handle can optionally be a file handle in Windows Sockets 2. It is possible to 
use socket handles with ReadFile, WriteFile, ReadFileEx, WriteFileEx, 
DuplicateHandle, and other Win32 functions. Not all transport service providers support 
this option. For an application to run over the widest possible number of service 
providers, it should not assume that socket handles are file handles. 


Windows Sockets 2 has expanded certain functions that transfer data between sockets 
using handles. The functions offer advantages specific to sockets for transferring data 
and include WSARecv, WSASend, and WSADuplicateSocket. 
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New Concepts, Additions, and Changes for Windows 
Sockets 2 


This section summarizes Windows Sockets 2 and describes the major changes and 
additions it contains. Windows Sockets 2 differs from Windows Sockets 1.1 in several 
ways, particularly in architecture. The new architecture, discussed in Windows Sockets 2 
Architecture, provides the foundation for many of the new concepts that have been 
incorporated into Windows Sockets 2. 


An overview of the additions and changes in Windows Sockets 2 follows the discussion 
of the new architecture. 


Many of the functions in Windows Sockets 2 are the same as in the other versions of 
sockets. However, there are several new functions, which are summarized in Summary 
of New Functions. For detailed information on how to use a specific function or feature, 
refer to the Reference section. 


‘Windows Sockets 2 Architecture - 


A number of Windows Sockets 2 features required substantial change in the Windows 
Sockets architecture. The resulting architecture is considerably different from previous 
versions, but the benefits are numerous. Foremost among these is Simultaneous Access 
to Multiple Transport Protocols, explained in detail in the following section. 


Other features include the adoption of protocol-independent name resolution facilities, 
provisions for layered protocols and protocol chains, and a different mechanism for 
Windows Sockets service providers to offer extended, provider-specific functionality. 


Simultaneous Access to Multiple Transport Protocols 


In order to provide simultaneous access to multiple transport protocols, the architecture 
has changed for Windows Sockets 2. With Windows Sockets 1.1, the vendor of the 
TCP/IP protocol stack supplies the DLL that implements the Windows Sockets interface. 
The interface between the Windows Sockets DLL and the underlying stack was both 
unique and proprietary. Windows Sockets 2 changes this model. It defines a standard 
Service Provider Interface (SPI) between the Windows Sockets DLL and protocol stacks. 
In this way, a single Windows Sockets DLL can simultaneously access multiple stacks 
from different vendors. Furthermore, Windows Sockets 2 support is not limited to TCP/IP 
protocol stacks as it is in Windows Sockets 1.1. : 


The Windows Open System Architecture (WOSA)-compliant Windows Sockets 2 
architecture is shown in Figure 6-1. 
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Figure 6-1: Windows Sockets 2 Architecture. 

With the Windows Sockets 2 architecture, it is not necessary or desirable, for stack 
vendors to supply their own implementation of WS2_32.dll, since a single WS2_32.dll 
must work across all stacks. The WS2_32.dll and compatibility shims should be viewed 
_ in the same way as an operating system component. 


Backward Compatibility for Windows Sockets 1.1 Applications 


Windows Sockets 2 is backward compatible with Windows Sockets 1.1 on two levels: 
source and binary. This maximizes interoperability between Windows Sockets 
applications of any version and Windows Sockets implementations of any version. It also 
minimizes problems for users of Windows Sockets applications, network stacks, and 
service providers. Current Windows Sockets 1.1-compliant applications operate on a 
Windows Sockets 2 implementation without modification of any kind, as long as at least 
one TCP/IP service provider is properly installed. 


Source Code Compatibility 


Source code compatibility in Windows Sockets 2 means, with few exceptions, that all the 
Windows Sockets 1.1 functions are preserved in Windows Sockets 2. Windows Sockets 
1.1 applications that use blocking hooks should be modified since blocking hooks are no 
longer supported in Windows Sockets 2. (For more information, see Windows Sockets 
1.1 Blocking Routines and EINPROGRESS.) 


Existing Windows Sockets 1.1 application source code can ni éaally, be moved to the 
Windows Sockets 2 system by including the new header file, Winsock2.h, and 
performing a straightforward relink with the appropriate Windows Sockets 2 libraries. 
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Application developers are encouraged to view this as the first step in a full transition to 
Windows Sockets 2 because there are numerous ways in which a Windows Sockets 1.1 
application can be improved by exploring and using the new functionality in Windows 
Sockets 2. 


Binary Compatibility | 

A major design goal for Windows Sockets 2 was to enable existing Windows Sockets 1.1 
applications to work, unchanged at a binary level, with Windows Sockets 2. Since 
Windows Sockets 1.1 applications are TCP/IP-based, binary compatibility implies that 
TCP/IP-based Windows Sockets 2 Transport and Name Resolution Service Providers 
are present in the Windows Sockets 2 system. In order to enable Windows Sockets 1.1 
applications in this scenario, the Windows Sockets 2 system has an additional shim 
component supplied with it: a Version 1.1-compliant Winsock.dll. 


Installation guidelines for Windows Sockets 2 ensure there is no negative impact to 
existing Windows Sockets-based applications on an end-user system with the 
introduction of any Windows Sockets 2 components. (See Figure 6-2.) 


Windows; Windows 
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Application Application 
' Windows 
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is 
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Figure 6-2: Windows Sockets 1.1 Compatibility Architecture. 
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Important To obtain information about the underlying TCP/IP stack, Windows Sockets 
1.1 applications currently use certain members of the WSAData structure (obtained 
through a call to WSAStartup). These members include: IMAXSOCKETS, 
IMAXUDPDG, and LPVENDORINFO. 


While Windows Sockets 2 applications ignore these values (since they cannot uniformly 
apply to all available protocol stacks), safe values are supplied to avoid breaking 
Windows Sockets 1.1 applications. 


Making Transport Protocols Available to Windows Sockets 


A transport protocol must be properly installed on the system and registered with 
Windows Sockets to be accessible to an application. The Ws2_32.dll exports a set of 
functions to facilitate the registration process. This Includes creating a new registration 
and removing an existing one. 


When new registrations are created, the caller (that is, the stack vendor’s installation 
script) supplies one or more filled in WSAPROTOCOL_INFO structures containing a 

_ complete set of information about the protocol. (See the Welcome To Windows Sockets 
2 SPI for information on how this is accomplished.) Any transport stack installed in this 
manner is referred to as a Windows Sockets service provider. 


The Windows Sockets 2 SDK includes a small Windows applet, Sporder.exe, that allows 
the user to view and modify the order in which service providers are enumerated. By 
using this Sporder.exe, a user can manually establish a particular TCP/IP protocol stack 
as the default TCP/IP provider if more than one such stack is present. : 


The Sporder.exe applet exports functions from Sporder.dil to reorder the service 
providers. As a result, installation applications can use the interface of Sporder.dll to 
programmatically reorder service providers to suit their needs. 


Layered Protocols and Protocol Chains 


Windows Sockets 2 incorporates the concept of a layered protocol. A layered protocol is 
one that implements only higher-level communications functions while relying on an 
underlying transport stack for the actual exchange of data with a remote endpoint. An 
example of this type of layered protocol is a security layer that adds a protocol to the 
socket connection process in order to perform authentication and establish an encryption 
scheme. Such a security protocol generally requires the services of an pupdeny ng and 
reliable transport protocol such as TCP or SPX. 


The term base protocol refers to a protocol, such as TCP or SPX, that is fully capable of 
performing data communications with a remote endpoint. A layered protocol is a protocol 
that cannot stand alone, while a protocol chain is one or more layered protocols strung 
together and sce hooe by a base protocol. | 
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You can create a protocol chain if you design the layered protocols to support the 
Windows Sockets 2 SPI at both their upper and lower edges. A special 
WSAPROTOCOL_INFO structure refers to the protocol chain as a whole and describes 
the explicit order in which the layered protocols are joined. This is shown in Figure 6-3. 
Since only base protocols and protocol chains are directly usable by applications, they 
are the only ones listed when the installed protocols are enumerated with the 
WSAEnumProtocols function. 


WS2_ 32.DLL ie 


API 


SPI 


Layered F Protocol 
Layel red Protocol 


[> Base Protoed 


Figure 6-3: Layered Protocol Architecture. 


Using Multiple Protocols 


An application uses the WSAEnumProtocols function to determine which transport 
protocols and protocol chains are present, and to obtain information about eacn as 
contained in the associated WSAPROTOCOL_ INFO structure. | | 


In most instances, there is a single WSAPROTOCOL_INFO structure for each protocol 
or protocol chain. However, some protocols exhibit multiple behaviors. For example, the 
SPX protocol is message oriented (that is, the sender's message boundaries are 
preserved by the network), but the receiving socket can ignore these message 
boundaries and treat them as a byte stream. Thus, two different WSAPROTOCOL_ 


INFO structure entries could exist for SPX—one for each behavior. 
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In Windows Sockets 2, several new address family, socket type, and protocol values 
appear. Windows Sockets 1.1 supported a single address family (AF_INET) comprising 
a small number of well-known socket types and protocol identifiers. Windows Sockets 2 
retains the existing address family, socket type, and protocol identifiers for compatibility 
reasons, but it also supports new transport protocols with new media types. 


A Windows Sockets 2 clearinghouse allows protocol stack vendors to obtain unique 
identifiers for new address families, socket types, and protocols. FTP and World Wide 
Web servers supply current identifier/value mappings and use email to request allocation 
of new ones. This is the World Wide Web URL for the Windows Sockets 2 Identifier 
Clearinghouse: cn 


New, unique identifiers are not necessarily well known, but this should not pose a 
problem. Applications that need to be protocol-independent are encouraged to select a 
protocol on the basis of its suitability rather than the values assigned to their socket_type 
or protoco/ parameters. Protocol suitability is indicated by the communications attributes, 
such as message-versus-byte stream, and reliable-versus-unreliable, that are contained 
in the protocol WSAPROTOCOL_INFO structure. Selecting protocols on the basis of 
Suitability as opposed to well-known protocol names and socket types lets protocol- 

_ independent applications take advantage of new transport protocols and their associated 
media types, as they become available. 


_ The server half of a client/server application benefits by establishing listening sockets on 
all suitable transport protocols. Then, the client can establish its connection using any 
suitable protocol. For example, this would let a client application be unmodified whether 
it was running on a desktop iy connected through LAN or on a seule using a 
wireless network. 


Multiple Provider Restrictions on Select 


The select function is used to determine the status of one or more sockets in a set. For 
each socket, the caller can request information on read, write, or error status. A set of 
sockets is indicated by an FD_SET structure. . 


Windows Sockets 2 allows an application to use more than one service provider, but the 
select function is limited to a set of sockets associated with a single service provider. 
This does not in any way restrict an application from having multiple sockets open, 
through multiple providers. 3 


There are two ways to determine the status of a set of sockets that spans more than one 
service provider: — 


e Using’ the WSAWaitForMultipleEvents or r WSAEventSelect functions when 
blocking semantics are employed 


e Using the WSAAsyncSelect function when nonblocking operations a are employed. 
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When an application needs to use blocking semantics on a set of sockets that spans 
multiple providers, WSAWaitForMultipleEvents is recommended. The application can 
also use the WSAEventSelect function, which allows the FD_XXX network events (see 
WSAEventSelect) to associate with an event object and be handled from within the 
event object paradigm (described in Overlapped I/O and Event Objects). 


The WSAAsyncSelect function is recommended when nonblocking operations are 
preferred. This function is not restricted to a single provider because it takes a socket 
descriptor as an input parameter. 


Function Extension Mechanism 


The Windows Sockets .dll, Ws2_32.dll, is no longer supplied by each individual stack 
vendor. As a result, it is no longer possible for a stack vendor to offer extended 
functionality by just adding entry points to the Ws2_32.dll. To overcome this limitation, 
Windows Sockets 2 takes advantage of the new WSAloctl function to accommodate 
service providers who want to offer provider-specific functionality extensions. This 
mechanism assumes, of course, that an application is aware of a particular extension 
and understands both the semantics and syntax involved. Such information would 
typically be supplied by the service provider vendor. 


In order to invoke an extension function, the application must first ask for a pointer to the 
desired function. This is done through the WSAloctl function using the 
SIO_GET_EXTENSION_FUNCTION_POINTER command code. The input buffer to the 
WSAloctl function contains an identifier for the desired extension function while the 
output buffer contains the function pointer itself. The application can then invoke the 
extension function directly without passing through the Ws2_32.dll. 


The identifiers assigned to extension functions are globally unique identifiers (GUIDs) 
that are allocated by service provider vendors. Vendors who create extension functions 
are urged to publish full details about the function including the syntax of the function 
prototype. This makes it possible for common and popular extension functions to be 
offered by more than one service provider vendor. An application can obtain the function 
pointer and use the function without needing to know anything about the particular 
service provider that implements the function. 


Debug and Trace Facilities 
Windows Sockets 2 application developers need to isolate bugs in: 


e The application. 

e The Ws2_32.dll or one of the compatibility shim .dlls. 

e The service provider. Windows Sockets 2 addresses this need through a specially 
devised version of the Ws2_32.dll and a separate debug/trace .dll. This combination 


allows all procedure calls across the Windows Sockets 2 API or SPI to be monitored 
and, to some extent, controlled. | 
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Developers can use this mechanism to trace procedure calls, procedure returns, 
parameter values, and return values. Parameter values and return values can be altered 
on procedure call or procedure return. If desired, a procedure call can be prevented or 
redirected. With access to this level of information and control, a developer can isolate 
any problem in the application, Ws2_32.dll, or service provider. 


The Windows Sockets 2 SDK includes the debug Ws2_32.dll, a sample debug/trace .dlll, 
and a document containing a detailed description of the components. The sample 
debug/trace .dil is provided in both source and object form. Developers are free to use 
the source to develop versions of the debug/trace .dll that meet their specific needs. 


Name Resolution 


Windows Sockets 2 includes provisions for standardizing the way applications access 
and use the various network name resolution services. Windows Sockets 2 applications 
do not need to be aware of the widely differing interfaces associated with name services 
such as DNS, NIS, X.500, SAP, and others. An introduction to this topic and the details 
of the functions are currently located in Protocol-Independent Name Resolution. 


Overlapped I/O and Event Objects 


Windows Sockets 2 introduces overlapped I/O and requires that all transport providers 
support this capability. Overlapped I/O follows the model established in Win32 and can 
be performed only on sockets created through the WSASocket function with the 
WSA_FLAG_OVERLAPPED flag set or sockets created through the socket function. 


Note Creating a socket with the overlapped attribute has no impact on whether a 

_ socket is currently in blocking or nonblocking mode. Sockets created with the overlapped 
attribute can be used to perform overlapped |I/O—doing so does not change the blocking 
mode of a socket. Since overlapped I/O operations do not block, the blocking mode of a 
socket is irrelevant for these operations. 


For receiving, applications use the WSARecv or WSARecvFrom functions to supply 
buffers into which data is to be received. If one or more buffers are posted prior to the 
time when data has been received by the network, that data could be placed in the 
user’s buffers immediately as it arrives. Thus, it can avoid the copy operation that would 
_ otherwise occur at the time the recv or recvfrom function is invoked. If data is already 
present when receive buffers are posted, itis copied immediately into the user’s buffers. 


_ If data arrives when no receive buffers have been posted by the application, the network 
resorts to the familiar synchronous style of operation. That is, the incoming data is 
buffered internally until the application issues a receive call and thereby supplies a buffer 
into which the data can be copied. An exception to this is when the application uses 
setsockopt to set the size of the receive buffer to zero. In this instance, reliable 

_ protocols would only allow data to be received when application buffers had been posted 
and data on unreliable protocols would be lost. ag , 
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On the sending side, applications use WSASend or WSASendTo to supply pointers to 
filled buffers and then agree not to disturb the buffers in any way until the network has 
consumed the buffer’s contents. 


Overlapped send and receive calls return immediately. A return value of zero indicates 
that the I/O operation was completed immediately and that the corresponding completion 
indication already occurred. That is, the associated event object has been signaled, or a 
completion routine has been queued and will be executed when the calling thread gets 
into the alertable wait state. 


A return value of SOCKET_ERROR coupled with an error code of WSA_IO_PENDING 
indicates that the overlapped operation has been successfully initiated and that a 
subsequent indication will be provided when send buffers have been consumed or when 
a receive operation has been completed. However, for sockets that are byte-stream 
style, the completion indication occurs whenever the incoming data is exhausted, 
regardless of whether the buffers are full. Any other error code indicates that the 
overlapped operation was not successfully initiated and that no completion indication will 
be forthcoming. 


Both send and receive operations can be overlapped. The receive junctions can be 
invoked several times to post receive buffers in preparation for incoming data, and the 
send functions can be invoked several times to queue multiple buffers to send. While the 
application can rely upon a series of overlapped send buffers being sent in the order 
supplied, the corresponding completion indications might occur in a different order. 
Likewise, on the receiving side, buffers can be filled in the order they are supplied, but 
the completion indications might occur in a different order. 


Canceling individual overlapped operations pending on a given socket is impossible. 
However, the closesocket function can be called to close the socket and eventually 
discontinue all pending operations. 


The deferred completion feature of overlapped I/O is also available for WSAloctiI, wien 
is an enhanced version of ioctlsocket. 


Event Objects 


Introducing overlapped I/O requires a mechanism for applications to unambiguously 
associate send and receive requests with their subsequent completion indications. In 
Windows Sockets 2, this is accomplished with event objects that are modeled after 
Win32 events. Windows Sockets event objects are fairly simple constructs that can be 
created and closed, set and cleared, and waited upon and polled. Their prime utility is 
the ability of an application to block and wait until one or more event objects become set. 


Applications use WSACreateEvent to obtain an event object handle that can then be 


supplied as a required parameter to the overlapped versions of send and receive calls 
(WSASend, WSASendTo, WSARecv, WSARecvFrom). The event object, which is 


cleared when first created, is set by the transport providers when the associated 
overlapped I/O operation has completed (either successfully or with errors). Each event 


object created by WSACreateEvent should have a matching WSACloseEvent to 
destroy it. 
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Event objects are also used in WSAEventSelect to associate one or more FD_XXX 
network events with an event object. This is described in Asynchronous Notification 
Using Event Objects. 


In 32-bit environments, event object—related functions, including WSACreateE vent, 
WSACloseEvent, WSASetEvent, WSAResetEvent, and WSAWaitForMultipleEvents 
are directly mapped to the corresponding native Win32 functions, using the same 
function name, but without the WSA prefix. 


Receiving Completion Indications 


several options are available for receiving completion indications, thus providing 
applications with appropriate levels of flexibility. These include: waiting (or blocking) on 
event objects, polling event objects, and socket I/O completion routines. 


Blocking and Waiting for Completion Indication 

Applications can block while waiting for one or more event objects to become set using 
the WSAWaitForMultipleEvents function. In Win32 implementations, the process or 
thread truly blocks. Since Windows Sockets 2 event objects are implemented as Win32 
events, the native Win32 function, WaitForMultipleObjects can also be used for this 
purpose. This is especially useful if the thread needs to wait on both socket and non- 
socket events. 


Polling for Completion Indication 

Applications that prefer not to block can use the WSAGetOverlappedResult function to 
poll for the completion status associated with any particular event object. This function | 
_ indicates whether or not the overlapped operation has completed, and if completed, 
arranges for the WSAGetLastError function to retrieve the error status of the 
overlapped operation. 


Using Socket I/O Completion Routines - | 

The functions used to initiate overlapped I/O (WSASend, WSASendTo, WSARecv, 
WSARecvFrom) ail take /oCompletionRoutine as an optional input parameter. This is a 
pointer to an application-specific function that is called after a successfully initiated 
overlapped I/O operation completes (successfully or otherwise). The completion routine 
follows the same rules as stipulated for Win32 file I/O completion routines. That is, the 
completion routine is not invoked until the thread is in an alertable wait state, such as 
when the function WSAWaitForMultipleEvents is invoked with the FALERTABLE flag 
set. An application that uses the completion routine option for a particular overlapped I/O 
request may not use the wait option of WSAGetOverlappedResult for that same 

| overlapped /O request. 


The transports allow an application to invoke send and receive operations: from within 
the context of the socket I/O completion routine and guarantee that, for a given socket, 
I/O completion routines will not be nested. This permits time-sensitive data transmissions 
to occur entirely within a preemptive context. 
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Summary of Overlapped Completion Indication Mechanisms 


The particular overlapped I/O completion indication to be used for a given overlapped 
operation is determined by whether the application supplies a pointer to a completion 
function, whether a WSAOVERLAPPED structure is referenced, and by the value of the 
hEvent member within the WSAOVERLAPPED structure (if supplied). The following 
table summarizes the completion semantics for an overlapped socket and shows the 
various combinations of lpOverlapped, hEvent, and IpCompletionRoutine: 


lpOverlapped hEvent IpCompletionRoutine Completion Indication 
NULL Not Ignored Operation completes 
applicable synchronously. It behaves as if 
it were a non-overlapped 
socket. 
INULL NULL NULL Operation completes 


overlapped, but there is no 
Windows Sockets 2-supported 
completion mechanism. The 
completion port mechanism (if 
supported) can be used in this 
case. Otherwise, there is no 
completion notification. 

INULL INULL NULL - Operation completes 

i overlapped, notification by 

signaling event object. 

INULL Ignored INULL. Operation completes 
overlapped, notification by 
scheduling completion routine. 


Asynchronous Notification Using Event Objects 


The WSAEventSelect and WSAEnumNetworkEvents functions are provided to 
accommodate applications such as daemons and services that have no user interface 
(and hence do not use Windows handles). The WSAEventSelect function behaves 
exactly like the WSAAsyncSelect function. However, instead of causing a Windows 
message to be sent on the occurrence of an FD_XXX network event (for example, 
FD_READ and FD_WRITE), an application-designated event object is set. 


Also, the fact that a particular FD_XXX network event has occurred is remembered by 
the service provider. The application can call WSAEnumNetworkEvents to have the 
current contents of the network event memory copied to an application-supplied buffer 
and to have the network event memory automatically cleared. If needed, the application 
can also designate a particular event object that is cleared along with the network event 
memory. 7 


Chapter 6 Winsock 2 API Overview 77 


Flow Specification Quality of Service 


Quality of Service is implemented in Windows 2000 through various Windows 2000 QOS 
components. For details and implementation guidelines, see the separate section under 
the Networking Services node of the Platform SDK titled Quality of Service. 


QOS Templates 


For details about QOS templates, see the chapters later in this wolinie that address 
QOS, or see the Platform SDK section titled Quality of Service. 


Default Values 


For details and implementation guidelines about Quality of Service, the FLOWSPEC 
structure, and FLOWSPEC’s default values, see the separate section under the 
Networking Services node of the Platform SDK titled Quality of Service. The 
FLOWSPEC structure is defined in the Quality of Service section’s reference section. 


Socket Groups 


All use of Socket Groups is reserved. 


Shared Sockets | 


The WSADuplicateSocket function is introduced to enable socket sharing across 
processes. A source process calls WSADuplicateSocket to obtain a special 
WSAPROTOCOL_INFO structure for a target process identifier. It uses some | 
interprocess communications (IPC) mechanism to pass the contents of this structure toa 
target process. The target process then uses the WSAPROTOCOL_INFO structure ina 
call to WSPSocket. The socket descriptor returned by this function will be an additional 
socket descriptor to an underlying socket which thus becomes shared. Sockets can be 
shared among threads in a given process without using the WSADuplicateSocket 
function because a socket descriptor is valid in all threads of a process. 


The two (or more) descriptors that reference a shared socket can be used independently 
as far as I/O is concerned. However, the Windows Sockets interface does not implement 
any type of access control, so the processes must coordinate any operations on a 
shared socket. A typical example of sharing sockets is to use one process for creating 
sockets and establishing connections. This process then hands off sockets to other 
processes that are responsible for information exchange. _ 


The WSADuplicateSocket function creates socket descriptors and not the uinderlyirig 

~ socket. As a result, all the states associated with a socket are held in common across all 
the descriptors. For example, a setsockopt operation performed using one descriptor is | 
subsequently visible using a getsockopt from any or all descriptors. A process can call 
closesocket on a duplicated socket and the descriptor will become deallocated. The 
underlying socket, however, remains ope) until closesocket | is called with the last 
remaining descriptor. 
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Notification on shared sockets is subject to the usual constraints of the 
WSAAsyncSelect and WSAEventSelect functions. Issuing either of these calls using 
any of the shared descriptors cancels any previous event registration for the socket, 
regardless of which descriptor was used to make that registration. Thus, for example, it 
would not be possible to have process A receive FD_READ events and process B 
receive FD_WRITE events. For situations when such tight coordination is required, it is 
suggested that developers use threads instead of separate processes. | 


Enhanced Functionality During Connection Setup and Teardown 


The WSAAccept function lets an application obtain caller information such as caller 
identifier and QOS before deciding whether to accept an incoming connection request. 
This is done with a callback to an application-supplied condition function. 


User-to-user data specified by parameters in the WSAConnect function and the 
condition function of WSAAccept can be transferred to the peer during connection 
establishment, provided this feature is supported by the service provider. 


Itis also possible (for protocols that support this) to exchange user data between the 
endpoints at connection teardown time. The end that initiates the teardown can call the 
WSASendDisconnect function to indicate that no more data be sent and to initiate the 
connection teardown sequence. For certain protocols, part of teardown is the delivery of 
disconnect data from the teardown initiator. After receiving notice that the remote end 
has initiated teardown (typically by the FD_CLOSE indication), the 
WSARecvDisconnect function can be called to receive the disconnect data, if any. 


To illustrate how disconnect data can be used, consider the following scenario. The 
client half of a client/server application is responsible for terminating a socket 
connection. Coincident with the termination, it provides (using disconnect data) the total 
number of transactions it processed with the server. The server in turn responds with the 
cumulative total of transactions that it has processed with all clients. The sequence of 
calls and indications might occur as follows. © 


Client side | 7 Server side 


(1) Invoke WSASendDisconnect to 
conclude session and supply transaction 
total. 


(2) Get FD_CLOSE, recv with a return 
value of zero, or WSAEDISCON error 
return from WSARecv indicating graceful | 
shutdown in progress. 


(3) Invoke WSARecvDisconnect to get 


client's transaction total. 
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Client side Server side 


(4) Compute cumulative grand total of all 
transactions. 


(5) Invoke WSASendDisconnect to 
transmit grand total. 


(6) Receive FD_CLOSE indication. (5a) Invoke closesocket. 


(7) Invoke WSARecvDisconnect to 
receive and store cumulative grand total of 
transactions. 


(8) ee closesocket 


Note Step (5a) must follow step (5), but has no timing relationship with 
step (6), (7), or (8). 


Extended Byte-Order Conversion Routines 


Windows Sockets 2 does not assume that the network byte order for all protocols is the 
same. A set of conversion routines is supplied for converting 16-bit and 32-bit quantities 
to and from network byte order. These routines take as an input parameter the socket 
handle that has a WSAPROTOCOL_INFO structure associated with it. The 
NetworkByteOrder member of the WSAPROTOCOL_INFO structure specifies the 
desired network byte order (currently either big-endian or little-endian). 


Support for Scatter/Gather I/O in the API 


The WSASend, WSASendTo, WSARecv, and WSARecvFrom functions all take an 
array of application buffers as input parameters and can be used for scatter/gather (or 
vectored) I/O. This can be very useful in instances where portions of each message 
being transmitted consist of one or more fixed-length header components in addition to 
message body. Such header components need not be concatenated by the application 
into a single contiguous buffer prior to sending. Likewise on receiving, the header 
components can be automatically split off into separate buffers, leaving the message 
body pure. 


When receiving into multiple buffers, completion occurs as data arrives from the network, 
regardless of whether all the suppres buffers are utilized. 


Protocol- -Independent Multicast and Multipoint 


Windows Sockets 2 provides a generic method for utilizing the multipoint and multicast 

capabilities of transports. This generic method implements these features just as it 

allows the basic data transport capabilities of numerous transport protocols to be 

accessed. The term multipoint | is used netsatlel to refer to both multicast and multipoint 
~ communications. 
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Current multipoint implementations (for example, IP multicast, ST-Il, T.120, and ATM 
UNI) vary widely. How nodes join a multipoint session, whether a particular node is 
designated as a central or root node, and whether data is exchanged between all nodes 


or only between a root node and the various leaf nodes differ among implementations. 


The WSAPROTOCOL_INFO structure for Windows Sockets 2 is used to declare the 
various multipoint attributes of a protocol. By examining these attributes, the programmer 
knows what conventions to follow with the applicable Windows Sockets 2 functions to set 
up, utilize, and tear down multipoint sessions. 


Following is a Summary of the features of Windows Sockets 2 that support multipoint. 


e Two-attribute bits in the WSAPROTOCOL_INFO structure. 

e Four flags defined for the dwFlags parameter of the WSASocket function. 

e One function, WSAJoinLeaf, for adding leaf nodes into a multipoint session 

e Two WSAloctl command codes for controlling multipoint loopback and establishing 


the scope for multicast transmissions. (The latter corresponds to the IP multicast 
time-to-live or TTL parameter.) 


Note The inclusion of these multipoint features in Windows Sockets 2 does not 
preclude an application from using an existing protocol-dependent interface, such as the 
Deering socket options for IP multicast. 


See Multipoint and Multicast Semantics for detailed information on how the various 
multipoint schemes are characterized and how the applicable features of Windows 
Sockets 2 are utilized. | 


summary of New Socket Options 


Value 


The new socket options for Windows Sockets 2 are summarized in the following table. 
See getsockopt and setsockopt for detailed information on these options. The other 
new protocol-specific socket options can be found in the Protocol-specific Annex (a 
separate document included with the Platform SDK). 


Type Meaning Default . Note 
SO_GROUP_ID GROUP Reserved. _ NULL Get only 
SO_GROUP_ — int _ Reserved. 0 
PRIORITY | 
SO_MAX_MSG_ int Maximum outbound (send) Implementation Get only 
SIZE size of a message for dependent 


- message-oriented socket 
types. There is no provision 
for finding out the maximum 
inbound message size. Has 
no meaning for stream- 
oriented sockets. 
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Value Type Meaning Default Note 
SO_PROTOCOL__. structure Description of protocol Protocol Get only 
INFO WSAPROTO __ information for protocol thatis | dependent 

COL_INFO bound to this socket. 
PVD_CONFIG char FAR * An opaque data structure Implementation 


object containing configuration 
information of the service 
provider. 


dependent 


Summary of New Socket loctl Opcodes 


The new socket ioctl opcodes for Windows Sockets 2 are summarized in the followin 
table. See WSAloct!l for detailed information on these opcodes. The WSAloctl function 
also supports all the ioctl opcodes specified in toctlsocket. The other new protocol- 
specific ioctl opcodes can be found in the Protocol-specific Annex (a separate document 
included with the Platform SDK). 


Opcode 
SIO_ASSOCIATE_ 
HANDLE 


SIO_ENABLE_ 
CIRCULAR_QUEUEING . 


SIO_FIND_ROUTE 
SIO_FLUSH 


SIO_GET_BROADCAST_ 
ADDRESS 


SIO_GET_QOS 
~ SIO_GET_GROUP_QOS 


SIO_MULTIPOINT_ 
LOOPBACK — 


Input Type 


Companion 
API 

dependent 
<not used> 


Structure 
SOCKADDR 


<not used> 


<not used> 


<not used> 


<not used> 
BOOL 


Output Type 


<not used> 


_<not used> 


<not used> 


<not used> 


Structure 
SOCKADDR 


QOS 


QOS 
<not used> 


Meaning 


Associate the socket with the — 
specified handle of a 
companion interface. 


Circular queuing is enabled. 


| Request the route to the 


specified address to be 
discovered. 

Discard current contents of 
the sending queue. 

Retrieve the protocol-specific 
broadcast address to be used 
in sendto/WSASendTo. | 


- Retrieve current flow 


specification(s) for the socket. 
Reserved. 


Control whether data sent in a 
multipoint session will also be 

received by the same socket | 
on the local host. 


(continued) 
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(continued) - 
Opcode Input Type 
SIO_MULTICAST_SCOPE int | 


SIO_SET_QOS QOS 


SIO_SET_GROUP_QOS QOS 


SIO_TRANSLATE_ int 
HANDLE 
SIO_ROUTING_ SOCKADDR 


INTERFACE_QUERY 


SIO_ROUTING SOCKADDR 
_INTERFACE_CHANGE | 


SIO_ADDRESS__ <not used> 
LIST_QUERY 

SIO_ADDRESS <not used> 
LIST CHANGE 


Summary of New Functions 


Output Type 


‘<not used> 


<not used> 


<not used> 


Companion API 
dependent 


SOCKADDR 


<not used> 


SOCKET_ 
ADDRESS _ 
LIST 


<not used> 


Meaning 


Specify the scope over which 
multicast transmissions will 
occur. | 


Establish new flow 
specification(s) for the socket. 


Reserved. 


Obtain a corresponding 
handle for socket s that is 
valid in the context of a 
companion interface. 


Obtain the address of local 
interface which should be 
used to send to the specified 
address. 


Request notification of 
changes in information 
reported through 
SIO_ROUTING_ 
INTERFACE_QUERY for the 
specified address. 


Obtain the list of addresses to 
which application can bind. 


Request notification of 
changes in information 
reported through 
SIO_ADDRESS_LIST_ 
QUERY 


The new API functions for Windows Sockets 2 are summarized in the table on the 


following page. 


Data Transport Functions 
Function 


WSAAccept! 


WSACloseEvent 
WSAConnect! 


WSACreateEvent 
WSADuplicateSocket 
WSAEnumNetworkEvents 
WSAEnumProtocols 
WSAEventSelect 
WSAGetOverlappedResult 
WSAGetQOSByName 


WSAHton! 
WSAHtons 
WSAlocti' 
WS<AvJoinLeaf! 
WSANtohI 
WSANtohs 


WSAProviderConfigChange 


WSARecv' 


WSARecvDisconnect 
WSARecvFrom! 
WSAResetEvent 
WSASend! 


WSASendDisconnect 
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Description 

An extended version of accept which allows for 
conditional acceptance. 

Destroys an event object. 


An extended version of connect which allows for 
exchange of connect data and QOS specification. 


Creates an event object. 

Creates a new socket descriptor for a shared socket. 
Discovers occurrences of network events. 

Retrieves information about each available protocol. 
Associates network events with an event object. 
Gets completion status of overlapped operation. 


Supplies QOS parameters based on a well-known 
service name. 


Extended version of htonl. 

Extended version of htons. 

Overlapped-capable version of ioctlsocket. 

Joins a leaf node into a multipoint session. 

Extended version of ntohl. 

Extended version of ntohs. 

Receive notifications of service = PlOvider= being 
installed/removed. 

An extended version of recv which accommodates 
scatter/gather I/O, overlapped sockets, and cprewiges 
the flags parameter as IN OUT. 

Terminates reception on a socket and retrieves the 
disconnect data, if the socket is connection-oriented. 
An extended version of reevfrom which 
accommodates scatter/gather I/O, overlapped 
sockets, and provides the flags parameters as IN OUT. 
Resets an event object. : 

An extended version of send which accommodates 
scatter/gather I/O and overlapped sockets. 

Initiates termination of a socket connection and 
optionally sends disconnect data. ; ra 
(continued) 
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(continued) 

Function | Description 

WSASendTo! An extended version of sendto which accommodates 
scatter/gather I/O and overlapped sockets. 

WSASetEvent Sets an event object. 

WSASocket An extended version of socket which takes a 


WSAPROTOCOL_INFO structure as input and allows 
overlapped sockets to be created. 


WSAWaitForMultipleEvents' Blocks on multiple event objects. 


Name Registration and Resolution Functions 


Function 


WSAAddressToString 


WSAEnumNameSpaceProviders 


WSAGetServiceClassInfo 
WSAGetServiceClassNameByClassid 
WSAlInstallServiceClass 


WSALookupServiceBegin 
WSALookupServiceEnd 
WSALookupServiceNext 


WSARemoveServiceClass 
WSASetService 


WSAStringToAddress 


Description 


Converts an address structure into a human- 
readable numeric string. 


Retrieves the list of available Name 
Registration and Resolution service 
providers. 


Retrieves all of the class-specific information 
pertaining to a service class. 


Returns the name of the service associated 
with the given type. 


Creates a new new service class type and 
stores its class-specific information. 


Initiates a client query to retrieve name 
information as constrained by a 
WSAQUERYSET data structure. 


Finishes a client query started by 
WSALookupServiceBegin and frees 
resources associated with the query. 


Retrieves the next unit of name information 
from a client query initiated by 
WSALookupServiceBegin. 


Permanently removes a service class type. 
Registers or removes from the registry a 
service instance within one or more 
namespaces. | 

Converts a human-readable numeric string 


to a socket address structure suitable for 
passing to Windows Sockets routines. 


1 The routine can block if acting on a blocking socket. 
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Windows Sockets Programming Considerations 


This section provides programmers with important information on a number of topics. It 
is especially pertinent to those who are porting socket applications from UNIX®-based 
environments or who are upgrading their Windows Sockets 1.1 applications to Windows 
Sockets 2. 


Deviation from Berkeley Sockets 


There are a few limited instances where Windows Sockets has had to divert from strict 
adherence to the Berkeley conventions, usually due to implementation difficulties in the | 
Microsoft® Windows environment. 


socket Data Type 


A new data type, SOCKET, has been defined. This is needed because a Windows 
Sockets application cannot assume that socket descriptors are equivalent to file 
descriptors as they are in UNIX. Furthermore, in UNIX, all handles, including socket 
handles, are small, non-negative integers, and some applications make assumptions 
that this will be true. Windows Sockets handles have no restrictions, other than that the 
value INVALID_SOCKET is not a valid socket. Socket handles may take any value in the 
range 0 to INVALID_SOCKET-—1. 


Because the SOCKET type is unsigned, compiling existing source code from, for 
example, a UNIX environment may lead to compiler warnings about signed/unsigned 
data type mismatches. 


This means, for example, that checking for errors when the socket and accept routines 
return should not be done by comparing the return value with —1, or seeing if the value is 
negative (both common, and legal, approaches in BSD). Instead, an application should 
use the manifest constant INVALID_SOCKET as defined in Winsock.h. For example: 


Typical BSD Style 


Preferred Style 
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Select and FD : 


Because a socket is no longer represented by the UNIX- -style small non-negative integer, 
the implementation of the select function was changed in Windows Sockets. Each set of 
sockets is still represented by the FD_SET type, but instead of being stored as a bitmask 
the set is implemented as an array of sockets. To avoid potential problems, applications 
must adhere to the use of the FD_XXX macros to set, initialize, clear, and check the 
FD_SET structures. 


Error Codes—errno, h_errno and WSAGetLastError 


Error codes set by Windows Sockets are not made available through the errno variable. 
Additionally, for the getXbyY class of functions, error codes are not made available 
through the h_errno variable. Instead, error codes are accessed by using the 
WSAGetLastError function. This function is provided in Windows Sockets as a 
precursor (and eventually an alias) for the Win32 function GetLastError. This is 
intended to provide a reliable way for a thread in a multithreaded process to obtain per- 
thread error information. __ 


For compatibility with BSD, an application may choose to include a line of the form: 


This allows networking code which was written to use the global errno to work correctly 
in a single-threaded environment. There are, obviously, some drawbacks. If a source file 
includes code which inspects errno for both socket and nonsocket functions, this 
mechanism cannot be used. Furthermore, it is not possible for an application to assign a 
new value to errno. (In Windows Sockets the function MSR Jet AStEIror: may be used 
for this purpose.) — 


Typical BSD Style 


Preferred Style 


Although error constants consistent with Berkeley Sockets 4.3 are provided for 
compatibility purposes, applications should, where possible, use the WSA error code 
definitions. This is because error codes returned by certain Windows Sockets routines 
fall into the standard range of error codes as defined by Microsoft® C®. A better version 
of the preceding source code fragment is shown on the following page. 
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This specification defines a recommended set of error codes, and lists the possible 
errors that can be returned as a result of each function. It may be the case in some 
implementations that other Windows Sockets error codes are returned in addition to 
those listed, and applications should be prepared to handle errors other than those 
enumerated under each function description. However Windows Sockets does not return 
any value that is not enumerated in the table of legal Windows Sockets errors given in 
the section Error Codes. 


Pointers 


All pointers used by applications with Windows Sockets should be FAR although this is 
only relevant to 16-bit applications and meaningless in a 32-bit. To facilitate this, data 
type definitions such as LPHOSTENT are provided. 


Renamed Functions 


In two cases it was necessary to rename functions that are used in Berkeley Sockets in 
_order to avoid clashes with other Win32 API functions. 


Close and Closesocket 


Sockets are represented by standard file descriptors in Berkeley Sockets, so the close 
function can be used to close sockets as well as regular files. While nothing in the 
Windows Sockets prevents an implementation from using regular file handles to identify 
sockets, nothing requires it either. Sockets must be closed by using the closesocket 
routine. Using the close routine to close a socket is incorrect and the effects of doing so 
are undefined by this specification. 


| loctl and loctlsocket/WSAloct! 


Various C language run-time systems use the IOCTL routine for purposes unrelated to 
Windows Sockets. As a consequence, the ioctlsocket function and the WSAloctlI | 
function were defined to handle socket functions that were performed by IOCTL and 
fentl in the Berkeley Software Distribution. 


Maximum Number of Sockets Supported 
The maximum number of sockets supported by a particular Windows Sockets service 
provider is implementation specific. An application should make no assumptions about 


the availability of a certain number of sockets. For more information on this topic see 
WSAStartup. | | 


The maximum number of sockets that an application can actually use is independent of 
the number of sockets supported by a particular implementation. The maximum number 
of sockets that a Windows Sockets application can use is determined at compile time by 
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| the manifest constant FD_SETSIZE. This value is used in constructing the FD_SET 
structures used in select. The default value in Winsock2.h is 64. If an application is 
designed to be capable of working with more than 64 sockets, the implementer should 
define the manifest FD_SETSIZE in every source file before including Winsock2.h. One 
way of doing this may be to include the definition within the compiler options in the 
makefile. For example, you could add “-DFD_SETSIZE=128" as an option to the 
compiler command line for Microsoft C. It must be emphasized that defining 
FD_SETSIZE as a particular value has no effect on the actual number of sockets 
provided by a Windows Sockets service provider. 


Include Files 


A number of standard Berkeley include files are supported for ease of porting existing 
source code based on Berkeley sockets. However, these Berkeley header files merely 
include the Winsock2.h include file, and it is therefore sufficient (and recommended) that 
Windows Sockets application source files just include Winsock2.h. 


Return Values on Function Failure 


The manifest constant SOCKET_ERROR is provided for checking function failure. 
Although use of this constant is not mandatory, it is recommended. The following 
example illustrates the use of the SOCKET_ERROR constant. 


Typical BSD Style 


Service Provided Raw Sockets 


The Windows Sockets specification does not mandate that a Windows Sockets service 
provider support raw sockets, that is, sockets of type SOCK_RAW. However, service 
providers are encouraged to supply raw socket support. A Windows Sockets-compliant 
application that wishes to use raw sockets should attempt to open the socket with the 
socket call, and if it fails either attempt to use another socket type or indicate the failure 
to the user. 
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Byte Ordering | 
Care must always be taken to account for any differences between the byte ordering 
used by Intel® architecture and the byte ordering used on the wire by individual transport 
protocols. Any reference to an address or port number passed to or from a Windows 
_ Sockets routine must be in the network order for the protocol being utilized. In the case 
of IP, this includes the IP address and port parameters of a SOCKADDF_IN structure 
(but not the sin_family parameter). 


Consider an application that normally contacts a server on the TCP port corresponding 
to the time service, but provides a mechanism for the user to specify an alternative port. 
The port number returned by getservbyname is already in network order, which is the 
format required for constructing an address so that no translation is required. However, if 
the user elects to use a different port, entered as an integer, the application must convert 
this from host to TCP/IP network order (using the WSAHtons function) before using it to 
construct an address. Conversely, if the application were to display the number of the 
port within an address (returned by getpeername for example), the port number must be 
converted from network to host order (using WSANtohs) before it can be displayed. 


Since the Intel and Internet byte orders are different, the conversions described in the 
preceding are unavoidable. Application writers are cautioned that they should use the 
standard conversion functions provided as part of Windows Sockets rather than writing 
their own conversion code since future implementations of Windows Sockets are likely to 
run on systems for which the host order is identical to the network byte order. Only 
applications that use the standard conversion functions are likely to be portable. 


Windows Sockets Compatibility Issues 


Windows Sockets 2 continues to support all of the Windows Sockets 1.1 semantics and 
function calls except for those dealing with psuedo-blocking. Since Windows Sockets 2 
runs only in 32-bit, preemptively scheduled environments, there is no need to implement 
the psuedo-blocking found in Windows Sockets 1.1. This means that the 
WSAEINPROGRESS error code will never be indicated and that the following Windows - 
Sockets 1.1 functions are not available to Windows Sockets 2 applications: 


e WSACancelBlockingCall 

e WSAIlsBlocking | 

e WSASetBlockingHook 

e WSAUnhookBlockingHook 


Windows Sockets 1.1 programs that are written to utilize psuedo-blocking will continue to 
operate correctly since they link to either Winsock.dll or Wsock32.dll. Both continue to 
support the complete set of Windows Sockets 1.1 functions. In order for programs to 
become Windows Sockets 2 applications, some code modification must occur. In most 
cases, the judicious use of threads can be substituted to accommodate processing that _ 
was being accomplished with a blocking hook function. , 
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Default State for a Socket’s Overlapped Attribute 


The socket function created sockets with the overlapped attribute set by default in the 
first Wsock32.dll, the 32-bit version of Windows Sockets 1.1. In order to insure backward 
compatibility with currently deployed Wsock32.dll implementations, this will continue to 
be the case for Windows Sockets 2 as well. That is, in Windows Sockets 2 sockets 
created with the socket function will have the overlapped attribute. However, in order to 
be more compatible with the rest of the Win32 API, sockets created with WSASocket 
will not, default, have the overlapped attribute. This attribute will only be applied if the 
WSA_FLAG_OVERLAPPED bit is set. 


Windows Sockets 1.1 Blocking Routines and EINPROGRESS 


One major issue in porting applications from a Berkeley sockets environment to a 
Windows environment involves blocking; that is, invoking a function that does not return 
until the associated operation is completed. A problem arises when the operation takes 
an arbitrarily long time to complete: an example is a recv, which might block until data 
has been received from the peer system. The default behavior within the Berkeley 
sockets model is for a socket to operate in blocking mode unless the programmer 
explicitly requests that operations be treated as nonblocking. Windows Sockets 1.1 
environments could not assume preemptive scheduling. Therefore, it was strongly 


~ recommended that programmers use the nonblocking (asynchronous) operations if at all | 


possible with Windows Sockets 1.1. Because this was not always possible, the psuedo- 
blocking facilities described in the following were provided. 


Note Windows Sockets 2 only runs on preemptive 32-bit operating systems where 
deadlocks are not a problem. Programming practices recommended for Windows 
Sockets 1.1 are not necessary in Windows Sockets 2. 


Even on a blocking socket, some functions—bind, getsockopt, and getpeername for 
example—complete immediately. There is no difference between a blocking and a 
nonblocking operation for those functions. Other operations, such as recv, can complete 
immediately or take an arbitrary time to complete, depending on various transport 
conditions. When applied to a blocking socket, these operations are referred to as" 
blocking operations. All routines that can block are listed ay an Vasterisk | in the 
preceding and following tables. 


With 16-bit Windows Sockets 1.1, a blocking re that cannot complete immediately 
is handled by psuedo-blocking as follows. 


The service provider initiates the operation, then enters a loop in which it dispatches any 
Windows messages (yielding the processor to another thread, if necessary), and then 
checks for the completion of the Windows Sockets function. If the function has 
completed, or if WSACancelBlockingCall has been invoked, the blocking function 
completes with an appropriate result. 
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A service provider must allow installation of a blocking hook function that does not 
process messages in order to avoid the possibility of re-entrant messages while a 
blocking operation is outstanding. The simplest such blocking hook function would return 
FALSE. If a Windows Sockets DLL depends on messages for internal operation, it can 
execute PeekMessage(hMyWnd...) before executing the application blocking hook so 
that it can get its messages without affecting the rest of the system. 


In a 16-bit Windows Sockets 1.1 environment, if a Windows message is received for a 
process for which a blocking operation is in progress, there is a risk that the application 
will attempt to issue another Windows Sockets call. Because of the difficulty in managing 
this condition safely, Windows Sockets 1.1 does not support such application behavior. 
An application is not permitted to make more than one nested Windows Sockets function 
call. Only one outstanding function call is allowed for a particular task. The only 
exceptions are two functions that are provided to assist the programmer in this situation: 
WSAIsBlocking and WSACancelIBlockingCall. | 


The WSAIsBlocking function can be called at any time to determine whether or not a 
blocking Windows Sockets 1.1 call is in progress. Similarly, the — 
WSACance!BlockingCall function can be called at any time to cancel an in- progress 
blocking call. Any other nesting of Windows Sockets functions fails with the error 
“WSAEINPROGRESS”. 


It should be emphasized that this restriction applies to both blocking and nonblocking 
operations. For Windows Sockets 2 applications that negotiate version 2.0 or higher at 
the time of calling WSAStartup, no restriction on the nesting of operations exits. 
Operations can become nested under rare circumstances, such as during a WSAAccept 
conditional-acceptance callback, or if a service ae in turn invokes a Windows 
Sockets 2 function. 


Although this mechanism is sufficient for simple applications, it cannot support the 

complex message-dispatching requirements of more advanced applications (for 

example, those using the MDI model). For such applications, the Windows Sockets API 

_ includes the function WSASetBlockingHook, which allows the application to specify a 

Special routine which can be called instead of the default message dispatch routine 
described in the preceding. 


The Windows Sockets provider Calls the ploaking hook only if. all of the following are true: 
e The routine is one that is defined as being able to block. 

-@ The specified socket is a blocking socket. 

¢ The request cannot be completed immediately. 

(A socket is set to blocking by default, but the IOCTL FIONBIO or the WSAAsyncSelect 
function seta socket to nonblocking mode.) , 


The blocking hook is never called and the application does not need to be concerned 
with the re-entrancy issues the blocking hook can introduce, i an Hy appleeion follows the 
- guidelines on the following page. | 


92 Volume 1 Winsock and Q0S | 


e |t uses only nonblocking sockets. 


e it uses the WSAAsyncSelect and/or the WSAAsyncGetXByY routines instead of 
select and the getXbyY routines. 


_If a Windows Sockets 1.1 application invokes an asynchronous or nonblocking operation 
that takes a pointer to a memory object (a buffer or a global variable, for example) as an 
argument, it is the responsibility of the application to ensure that the object is available to 
Windows Sockets throughout the operation. The application must not invoke any 
Windows function that might affect the mapping or address viability of the memory 
involved. 


Graceful Shutdown, Linger Options, and Socket Closure 


The following material is provided as clarification for the subject of shutting down socket 
connections closing the sockets. It is important to distinguish the difference between 
shutting down a socket connection and closing a socket. 


Shutting down a socket connection involves an exchange of protocol messages between 
the two endpoints, hereafter referred to as a shutdown sequence. Two general classes 
of shutdown sequences are defined: graceful and abortive (also called hard). Ina 
graceful shutdown sequence, any data that has been queued but not yet transmitted can 
be sent prior to the connection being closed. In an abortive shutdown, any unsent data is 
lost. The occurrence of a shutdown sequence (graceful or abortive) can also be used to 
provide an FD_CLOSE indication to the associated applications signifying that a 

_ shutdown is in progress. 


Closing a socket, on the other hand, causes the socket handle to become deallocated so 
that the application can no longer reference or use the socket in any manner. 


In Windows Sockets, both the shutdown function, and the WSASendDisconnect 
function can be used to initiate a shutdown sequence, while the closesocket function is 
used to deallocate socket handles and free up any associated resources. Some amount 
of confusion arises, however, from the fact that the closesocket function implicitly 

~ causes a shutdown sequence to occur if it has not already happened. In fact, it has 
become a rather common programming practice to rely on this feature and to use 
closesocket to both initiate the shutdown sequence and deallocate the socket handle. 


To facilitate this usage, the sockets interface provides for controls by way of the socket 
option mechanism that allow the programmer to indicate whether the implicit shutdown 
sequence should be graceful or abortive, and also whether the closesocket function 
should linger (that is not complete immediately) to allow time for a graceful shutdown 
sequence to complete. These important distinctions and the ramifications of using 
closesocket in this manner are still not widely understood. 


By establishing appropriate values for the socket options SO_LINGER and 
SO_DONTLINGER, the types of behavior on the following page can be obtained with the 
closesocket function. 
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e Abortive shutdown sequence, immediate return from closesocket. 


e Graceful shutdown, delaying return until either shutdown sequence completes or a 
specified time interval elapses. If the time interval expires before the graceful 
shutdown sequence completes, an abortive shutdown sequence occurs, and 
closesocket returns. 


e Graceful shutdown, immediate return—allowing the shutdown sequence to complete 
in the background. Although this is the default behavior, the application has no way of 
knowing when (or whether) the graceful shutdown sequence actually completes. 


One technique that can be used to minimize the chance of problems occurring during 
connection teardown is to avoid relying on an implicit shutdown being initiated by 
closesocket. Instead, use one of the two explicit shutdown functions, shutdown or 
WSASendDisconnect. This in turn causes an FD_CLOSE indication to be received by 
the peer application indicating that all pending data has been received. To illustrate this, 
the following table shows the functions that would be invoked by the client and server 
components of an application, where the client is responsible for initiating a graceful 
shutdown. 


Client side 7 - Server side 


(1) Invokes shutdown(s, SD_SEND) to 
signal end of session and that client has 
no more data to send. | | | | 
| (2) Receives FD_CLOSE, indicating graceful 
shutdown in progress and that all data has | 
been received. 7 
(3) Sends any remaining response data. 


(5a) Gets FD_READ and calls recv to (4) Invokes shutdown(s, SD_SEND) to 
get any response data sent by server. indicate server has no more data to send. 


(5) Receives FD_CLOSE indication. (4a) Invokes closesocket. 
(6) Invokes closesocket. ad 


Note The timing sequence is maintained from step (1) to step (6) between the client 
and the server, except for steps (4a) and (5a), which only have local timing significance 
in the sense that step (5) follows step (5a) on the client side while step (4a) follows step 
(4) on the server side, with no timing relationship with the remote party. | 


Protocol-Independent Out-of-Band Data 

The stream socket abstraction includes the notion of out of band (OOB) data. Many | 
protocols allow portions of incoming data to be marked as special in some way, and 
these special data blocks can be delivered to the user out of the normal sequence. 
Examples include expedited data in X.25 and other OSI protocols, and urgent data in 
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BSD Unix’s use of TCP. The next section describes OOB data handling in a protocol- 
independent manner. A discussion of OOB data implemented using TCP urgent data 
follows it. In the each discussion, the use of recv also implies recvfrom, WSARecv, and 
WSARecvFrom, and references to WSAAsyncSelect also apply to WSAEventSelect. 


Protocol Independent OOB Data 


OOB data is a logically independent transmission channel associated with each pair of 
connected stream sockets. OOB data may be delivered to the user independently of 
normal data. The abstraction defines that the OOB data facilities must support the 
reliable delivery of at least one OOB data block at a time. This data block can contain at 
least one byte of data, and at least one OOB data block can be pending delivery to the 
user at any one time. For communications protocols that support in-band signaling (such 
as TCP, where the urgent data is delivered in sequence with the normal data), the 
system normally extracts the OOB data from the normal data stream and stores it 
separately (leaving a gap in the normal data stream). This allows users to choose 
between receiving the OOB data in order and receiving it out of sequence without having 
to buffer all the intervening data. It is possible to peek’ at out-of-band data. 


A user can determine if there is any OOB data waiting to be read using the ioctlsocket 
SIOCATMARK function. For protocols where the concept of the position of the OOB 
data block within the normal data stream is meaningful such as TCP, a Windows 
Sockets service provider maintains a conceptual marker indicating the position of the last 
byte of OOB data within the normal data stream. This is not necessary for the 
implementation of the ioctlsocket(SIOCATMARK) functionality—the presence or 
absence of OOB data is all that is required. 


For protocols where the concept of the position of the OOB data block within the normal 
data stream is meaningful, an application might process out-of-band data inline, as part 
of the normal data stream. This is achieved by setting the socket option SO_OOBINLINE 
with setsockopt. For other protocols where the OOB data blocks are truly independent 
of the normal data stream, attempting to set SO_LOOBINLINE will result in an error. An 
application can use the SIOCATMARK ioctlsocket command to determine whether 
there is any unread OOB data preceding the mark. For example, it can use this to 
resynchronize with its peer by ensuring that all data up to the mark in the data stream is 
discarded when appropriate. 


With SO_OOBINLINE disabled (the default setting): 


e Windows Sockets notifies an application of an FD_OOB event, if the application 
registered for notification with WSAAsyncSelect, in exactly the same way FD_READ 
is used to notify of the presence of normal data. That is, FD_OOB is posted when 
OOB data arrives with no OOB data previously queued. The FD_OOB is also posted 
when data is read using the MSG_OOB flag while some OOB data remains queued 
after the read operation has returned. FD_READ messages are not posted for 
OOB data. 


e Windows Sockets returns from select with the appropriate exceptfds socket set if 
OOB data is queued on the socket. 
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e The application can call recv with MSG_OOB to read the urgent data block at any 
time. The block of OOB data jumps the queue. 


e The application can call recv without MSG_OOB to read the normal data stream. The 
OOB data block does not appear in the data stream with normal data. If OOB data 
remains after any call to recv, Windows Sockets notifies the application with FD_OOB 
or with exceptfds when using select. 


_e For protocols where the OOB data has a position within the normal data stream, a 
single recv operation does not span that position. One recv returns the normal data 
before the mark, and a second recv is required to begin eedng data after the mark. 


With Soll OOBINLINE enabled: 


e FD_OOB messages are not posted for OOB data. OOB data is treated as normal for 
the purpose of the select and WSAAsyncSelect functions, and indicated by setting 
the socket in readfds or by sending an FD_READ message respectively. | 


e The application can not call recv with the MSG_OOB flag set to read the OOB data 
block. The error code WSAEINVAL is returned. 


e The application can call reev without the MSG_OOB iis set. Ary ¢ OOB data is 
delivered in its correct order within the normal data stream. OOB data is never mixed 
with normal data. There must be three read requests to get past the OOB data. The 
first returns the normal data prior to the OOB data block, the second returns the OOB 
data, the third returns the normal data following the OOB data. In other words, the | 

~ OOB data block boundaries are preserved. , 


The WSAAsyncSelect routine is particularly well suited to handling notification of the 
presence of out- of- band-data when SO_OOBINLINE is off. 


OOB Data in TCP 


| Important. The following discussion of out-of-band data, implemented using TCP 
urgent data, follows the model used i in the Berkeley software distribution. Users and 
implementers should be aware that: 


e There are, at present, two conflicting interpretations of REC iS (where the concept is | 
introduced). 


e The implementation of OOB data in the Berkeley Software Distribution (BSD) does" 
‘not conform to the Host Requirements laid down in RFC 1122. 


Specifically, the TCP urgent pointer in BSD points to the byte after the urgent data byte, 

~and an RFC-compliant TCP urgent pointer points to the urgent data byte. As a result, if 
an application sends urgent data from a BSD-compatible implementation to an 

~ RFC-1122 compatible implementation, the receiver reads the wrong urgent data byte 
(it reads the byte located after the correct byte in the data stream as the urgent 

data oe) | 
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To minimize interoperability problems, applications writers are advised not to use OOB 
data unless this is required to interoperate with an existing service. Windows Sockets 
suppliers are urged to document the OOB semantics (BSD or RFC 1122) that their 
product implements. 


Arrival of a TCP segment with the URG (for urgent) flag set indicates the existence of a 
single byte of OOB data within the TCP data stream. The OOB data block is one byte in 
size. The urgent pointer is a positive offset from the current sequence number in the 
TCP header that indicates the location of the OOB data block (ambiguously, as noted in 
the preceding). It might, therefore, point to data that has not yet been received. 


If SO_OOBINLINE is disabled (the default) when the TCP segment containing the byte 
pointed to by the urgent pointer arrives, the OOB data block (one byte) is removed from 
the data stream and buffered. If a subsequent TCP segment arrives with the urgent flag 
set (and a new urgent pointer), the OOB byte currently queued can be lost as it is 
replaced by the new OOB data block (as occurs in Berkeley Software Distribution). It is 
never replaced in the data stream, however. 


With SO_OOBINLINE enabled, the urgent data remains in the data stream. As a result, 
the OOB data block is never lost when a new TCP segment arrives containing urgent 
data. The existing OOB data “mark” is updated to the new position. 


Summary of Windows Sockets 2 Functions 


The following tables summarize the functions included in Windows Sockets 2, separated 
into two groups: Berkeley-style functions, and Microsoft Windows-specific Extension | 
functions that have been ratified as part of the Windows Sockets 2 specification. These 
tables do not include the Windows Sockets functions known that are used with 
Registration and Name Resolution. 


Socket Functions 


The Windows Sockets specification includes all the following Berkeley-style socket 
routines that were part of the Windows Sockets 1.1 API. 


Routine Meaning 


accept! An incoming connection is acknowledged and associated with an 
immediately created socket. The original socket is returned to the 
listening state. 


_ bind Assigns a local name to an unnamed socket. 
closesocket | Removes a socket from the per-process object reference table. Only 
_ blocks if SO_LINGER is set with a nonzero time-out on a blocking 
socket. 


connect! Initiates a connection on the specified socket 


Routine 


getpeername 
getsockname 
getsockopt 
htonl@ 


htons2 
inet_addr2 
inet_ntoa* 


loctlsocket 
listen 
ntohl2 


ntohs¢ 


recv! 
recvfrom! 
select! 
send! 
sendto! 
setsockopt 
shutdown | 
socket 
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Meaning 


Retrieves the name of the peer connected to the specified socket. 
Retrieves the local address to which the specified socket is bound. 
Retrieves options associated with the specified socket. 


Converts a 32-bit quantity from host-byte order to network-byte 
order. 


Converts a 16-bit quantity from host-byte order to network-byte 
order. 


Converts a character string representing a number in the Internet 
standard “.” notation to an Internet address value. 


Converts an Internet address value to an ASCII string in “.” notation 
that is, “a.b.c.d”. 


Provides control for sockets. 
Listens for incoming connections on a specified socket. 


Converts a 32- bit quantity from network-byte order to host-byte 
order. | 


Converts a 16-bit quantity from network byte order to host byte 
order. 


Receives data from a connected or unconnected socket. 
Receives data from either a connected or unconnected socket, 


~ Performs synchronous I/O multiplexing. 


Sends data to a connected socket. 

sends data to either a connected or unconnected socket. 
Stores options associated with the specified socket. 
Shuts down part of a full-duplex connection. 


Creates an endpoint for communication and returns a socket 
descriptor. 


1 The routine can block if acting ona blocking socket. 


2 The routine is retained for backward compatibility with Windows Sockets 1.1, and should only be used 
_ for sockets created with AF_INET address family. | 


Microsoft Windows-Specific Extension Functions 

The Windows Sockets specification provides a number of extensions to the standard set 

_ of Berkeley Sockets routines. Principally, these extended functions allow message or 
function-based, asynchronous access to network events, as well as enable overlapped 
I/O. While use of this extended API set is not mandatory for socket-based programming 
(with the exception of WSAStartup and WSACleanup), it is recommended for 
conformance with the Microsoft Windows programming paradigm. For features 
introduced in Windows Sockets 2, please see New Concepts, Additions and Changes for 
Windows SOcKels 2. | 
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Routine 


WSAAccept! 


‘WSAAsyncGetHostByAddr? ° 
WSAAsyncGetHostByName?: 3 
WSAAsyncGetProtoByName2: 3 
WSAAsyncGetProtoByNumber®: 3 
WSAAsyncGetServByName2: 2 
WSAAsyncGetServByPort2: ° 
WSAAsyncSelect® 
WSACancelAsyncRequest* * 


WSACleanup 


WSACloseEvent 
WSAConnect! 


WSACreateEvent 
WSADuplicateSocket 


WSAEnumNetworkE vents 
WSAEnumProtocols 


WSAEventSelect 
WSAGetLastError® 
WSAGetOverlappedResult 
WSAGetQOSByName 


WSAHtonl 
WSAHtons 
WSAloct!! 
-WSAdJoinLeaf" 
WSANtoh I 
WSANtohs 


Meaning 


An extended version of accept, which allows for 
conditional acceptance. 


A set of functions that provide asynchronous 
versions of the standard Berkeley getXbyY 
functions. For example, the 
WSAAsyncGetHostByName function provides 
an asynchronous, message-based 
implementation of the standard Berkeley 
gethostbyname function. 

Performs asynchronous version of select. 


Cancels an outstanding instance of a 
WSAAsyncGetXByY function. 


Signs off from the underlying Windows 
Sockets .dll. | 


Destroys an event object. 


An extended version of connect which allows for 
exchange of connect data and QOS 
specification. 


Creates an event object. 


Allows an underlying socket to be shared by 
creating a virtual socket. 


Discovers occurrences of network events. 


Retrieves information about each available 
protocol. 


Associates network events with an event object. 
Obtains details of last Windows Sockets error. 
Gets completion status of overlapped operation. 
Supplies-QOS parameters based on a well- 


-known service name. 


Extended version of htonl. 


Extended version of htons. | 


Overlapped-capable version of lIOCTL. 

Adds a multipoint leaf to a multipoint session. 
Extended version of ntohl. 

Extended version of ntohs. 


Routine 


WSAProviderConfigChange 


WSARecv'! 
WSARecvFrom!' 


WSAResetEvent 
WSASend! 


WSASendTo! 


WSASetEvent 
WSASetLastError® 


WSASocket _ 


WSAStartup* | 
WSAWaitForMultipleEvents' 
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Meaning 


Receives notifications of service providers being 
installed/removed. . 

An extended version of recv which 
accommodates scatter/gather I/O, overlapped 
sockets and provides the flags parameter 

as in, out. 

An extended version of recvfrom which 
accommodates scatter/gather I/O, overlapped 
sockets and provides the nage parameter 

as in, out. 

Resets an event object. 


An extended version of send which 
accommodates scatter/gather I/O and 
overlapped sockets. _ 


An extended version of sendto which 
accommodates scatter/gather /O and 
overlapped sockets. 


Sets an event object. 


Sets the error to be returned by a subsequent 
WSAGetLastError. 


An extended version of socket which takes a 
WSAPROTOCOL_INFO structure as input and 
allows overlapped sockets to be created. 


Initializes the underlying Windows Sockets .dl. 
Blocks on multiple event objects. | 


1 The routine can block if acting on a blocking socket. | 
2 The routine is always realized by the name resolution provider mariana with the default TCP/IP 


service provider, if any. 


3 The routine was originally a Windows Sockets 1.1 function 


Registration and Name Resolution 


Windows Sockets 2 includes a new set of API functions that standardize the way 
applications access and use the various network naming services. When using these 
new functions, Windows Sockets 2 applications need not be cognizant of the widely 
differing protocols associated with name services such as DNS, NIS, X.500, SAP, etc. 
To maintain full backward compatibility with Windows Sockets 1.1, all of the existing 
getXbyY and asynchronous WSAAsyncGetXbyY database lookup functions continue to 
be supported, but are implemented in the Windows Sockets service provider interface in — 
terms of the new name resolution capabilities. For more information, see the 
getservbyname and getservbyport functions. Also, see Compatible Name Resolution 
for TCP/IP in the Windows Sockets 1. 1 SPI. 
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Protocol-Independent Name Resolution 


In developing a protocol-independent client/server application, there are two basic 
requirements that exist with respect to name resolution and registration: 


e The ability of the server half of the application (service) to register its existence within 
(or become accessible to) one or more namespaces. 


e The ability of the client application to find the service within a namespace and obtain 
the required transport protocol and addressing information. 


For those accustomed to developing TCP/IP-based applications, this may seem to 
involve little more than looking up a host address and then using an agreed-upon port 
number. Other networking schemes however, allow the location of the service, the 
protocol used for the service, and other attributes to be discovered at run-time. To 
accommodate the broad diversity of capabilities found in existing name services, the 
Windows Sockets 2 interface adopts the model described in the following. 


Name Resolution Model 


A namespace refers to some capability to associate (as a minimum) the protocol and 
addressing attributes of a network service with one or more human-friendly names. 
Many namespaces are currently in wide use, including the Internet’s Domain Name 
system (DNS), the bindery and Netware Directory Services (NDS) from Novell®, X.500, — 
etc. These namespaces vary widely in how they are organized and implemented. Some 
of their properties are particularly important to understand from the perspective of 
Windows Sockets name resolution. 


Types of Namespaces 
There are three different types of namespaces in which a service could be registered: 


e Dynamic 
e Static 
e Persistent 


Dynamic namespaces allow services to register with the namespace on the fly, and for 
clients to discover the available services at run-time. Dynamic namespaces frequently 
rely on broadcasts to indicate the continued availability of a network service. Examples 
of dynamic namespaces include the SAP namespace used within a Netware® 
environment and the NBP namespace used by Appletalk®. : 


Static namespaces require all of the services to be registered ahead of time, that is, 
when the namespace is created. The DNS is an example of a static namespace. 
Although there is a programmatic way to resolve names, there is no programmatic way 
to register names. 


Persistent namespaces allow services to register with the namespace on the fly. Unlike 
dynamic namespaces however, persistent namespaces retain the registration © 
information in non-volatile storage where it remains until such time as the service 


Chapter 6 Winsock 2 API Overview 101 


requests that it be removed. Persistent namespaces are typified by directory services 
such as X.500 and the NDS (Netware Directory Service). These environments allow the 
adding, deleting, and modification of service properties. In addition, the service object 
representing the service within the directory service could have a variety of attributes 
associated with the service. The most important attribute for client applications is the 
service’s addressing information. 


Namespace Organization 


Many namespaces are arranged hierarchically. Some, such as x. 500 and NDS, allow 
unlimited nesting. Others allow services to be combined into a single level of hierarchy or 
group. This is typically referred to as a workgroup. When constructing a query, it is often 
necessary to establish a context point within a namespace hierarchy from which the 
search will begin. 


Namespace Provider Architecture 


Naturally, the programmatic interfaces used to query the various types of namespaces 
and to register information within a namespace (if supported) differ widely. A namespace 
provider is a locally-resident piece of software that knows how to map between the 
Windows Sockets namespace SPI and some existing namespace (which could be 
implemented locally or be accessed through the network). Figure 6-4 shows the 
namespace provider architecture. 


WS2 32.DLL 
Transport | | Name Space 
SPI SPI. 
Name Name 
Space Space 
| Provider Provider 
Local NS 
Interface 


Transport Transport 
| Service Service 


Locally 
Implemented 


Provider Provider 
| Name Space 


Figure 6-4: Namespace Provider Architecture. 


Note that it is possible for a given namespace, say DNS, to have more than one — 
namespace provider installed on a given machine. 3 


As mentioned above, the generic term service refers to the server-half ofa client/server 
application. In Windows Sockets, a service is associated with a service class, and each 
instance of a particular service has a service name which must be unique within the 
service class. Examples of service classes include FTP Server, SQL Server, XYZ Corp. 
Employee Info Server, etc. As the example attempts to illustrate, some service classes 

~ are well known while others are unique and specific to a particular vertical application. 
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In either case, every service class is represented by both a class name and a class 
identifier. The class name does not necessarily need to be unique, but the class 
identifier must be. Globally Unique Identifiers (GUIDs) are used to represent service — 
class identifiers. For well-known services, class names and class identifiers (GUIDs) 
have been pre-allocated, and macros are available to convert between, for example, 
TCP port numbers (in host-byte order) and the corresponding class identifier GUIDs. For 
other services, the developer chooses the class name and uses the eulagen: exe utility 
to generate a GUID for the class identifier. 


The notion of a service class exists to allow a set of attributes to be established that are 
held in common by all instances of a particular service. This set of attributes is provided 
at the time the service class is defined to Windows Sockets, and is referred to as the 
service class schema information. When a service is installed and made available on a 
host machine, that service is considered instantiated, and its service name is used to 
distinguish a particular instance of the service from other instances which may be known 
to the namespace. | 


Note that the installation of a service class only needs to occur on machines where the 
service executes, not on all of the clients which may utilize the service. Where possible, 
the Ws2_32.dll provides service class schema information to a namespace provider at 
the time an instantiation of a service is to be registered or a service query is initiated. 
The Ws2_32.dll does not, of course, store this information itself, but attempts to retrieve 
it from a namespace provider that has indicated its ability to supply this data. Since there 
is no guarantee that the Ws2_32.dll can supply the service class schema, namespace 
providers that need this information must have a falloack mechanism to obtain it through 
namespace-specific means. 


As noted above, the Internet has adopted what can be termed a host-centric service 
model. Applications needing to locate the transport address of a service generally must 
first resolve the address of a specific host known to host the service. To this address 
they add in the well-known port number and thus create a complete transport address. 
To facilitate the resolution of host names, a special service class identifier has been pre- 
allocated (SVCID_HOSTNAME). A query that specifies SVCID_HOSTNAME as the 
service class and uses the host name the service instance name will, if the query is 
successful, return host address information. 


In Windows Sockets 2, applications that are protocol-independent should avoid the need 
to comprehend the internal details of a transport address. Thus, the need to first get a 
host address and then add in the port is problematic. To avoid this, queries may also 
include the well-known name of a particular service and the protocol over which the 
service operates, such as FTP or TCP. In this case, a successful query returns a 
complete transport address for the specified service on the indicated host, and the 


application is not required to crack open a SOCKADDR structure. This is described in 
more detail in the following. : 


The Internet’s Domain Name System does not have a well- defined means to store 
service class schema information. As a result, DNS namespace providers can only 


~ accommodate well-known TCP/IP services for which a service class GUID has been 


preallocated. 
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In practice, this is not a serious limitation since service class GUIDs have been 
preallocated for the entire set of TCP and UDP ports, and macros are available to 
retrieve the GUID associated with any TCP or UDP port with the port expressed in host- 
byte order. Thus, all of the familiar services such as FTP, Telnet, Whois, etc. are well — 
supported. . 


Continuing with our service class example, instance names of the FTP service may be 
“alder.intel.com” or “rhino.microsoft.com” while an instance of the XYZ Corp. Employee 
Info Server might be named “XYZ Corp. Employee Info Server Version 3.5”. 


In the first two cases, the combination of the service class GUID for FTP and the 
machine name (supplied as the service instance name) uniquely identify the desired 
service. In the third case, the host name where the service resides can be discovered at 
service query time, so the service instance name does not need to include a host name. 


Summary of Name Resolution Functions 


The name resolution functions can be grouped into three categories: Service installation, 
client queries, and helper functions (and macros). The sections that follow identify the 

- functions in each ealegoly a and briefly describe their intengee use. Key data structures 
are also described. 7 3 : 


Service Installation 
e WSAinstallServiceClass 
e ‘WSARemoveServiceClass 
° WSASetService 


When ine required service class does not already exist, an epolicatoni uses 

_ WSAlnstaliServiceClass to install a new service class by supplying a service class 
name, a GUID for the service class identifier, and a series of WSANSCLASSINFO 
structures. These structures are each specific to a particular namespace, and supply 
common values such as recommended TCP port numbers or Netware SAP Identifiers. 
Aservice class can be removed by calling WSARemoveServiceClass and supplying 
the GUID corresponding to the class identifier. | 


Once a service class exists, specific instances of a service can be installed or removed 
through WSASetService. This function takes a WSAQUERYSET structure as an input 
parameter along with an operation code and operation flags. The operation code 
indicates whether the service is being installed or removed. The WSAQUERYSET 
structure provides all of the relevant information about the service including service class 
identifier, service name (for this instance), applicable namespace identifier and protocol 
information, and a set of transport addresses at which the service listens. Services 
should invoke WSASetService when they initialize to advertise their presence in dynamic 
ames : : 
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Client Query 

e WSAEnumNameSpaceProviders 
e WSALookupServiceBegin 

e WSALookupServiceNext 

e WSALookupServiceEnd 


The WSAEnumNameSpaceProviders function allows an application to discover which 
namespaces are accessible through Windows Sockets name resolution facilities. It also 
allows an application to determine whether a given namespace is supported by more 
than one namespace provider, and to discover the provider identifier for any particular 
namespace provider. Using a provider identifier, the application can restrict a query 
operation to a specified namespace provider. 


Windows Sockets’ namespace query operations involve a series of calls: 
WSALookupServiceBegin, followed by one or more calls to WSALookupServiceNext 
and ending with a call to WSALookupServiceEnd. WSALookupServiceBegin takes a 
WSAQUERYSET structure as input to define the query parameters along with a set of 
flags to provide additional control over the search operation. It returns a query handle 
which is used in the subsequent calls to WSALookupServiceNext and 
WSALookupServiceEnd. 


The application invokes WSALookupServiceNext to obtain query results, with results 
supplied in an application-supplied WSAQUERYSET buffer. The application continues to 
call WSALookupServiceNext until the error code WSA_E_NO_MORE is returned 
indicating that all results have been retrieved. The search is then terminated by a call to 
WSALookupServiceEnd. The WSALookupServiceEnd function can also be used to 
cancel a currently pending WSALookupServiceNext when called from another thread. 


In Windows Socket 2, conflicting error codes are defined for WSAENOMORE (10102) 
and WSA_E_NO_MORE (10110). The error code WSAENOMORE will be removed in a 
future version and only WSA_E_NO_MORE will remain. For Windows Socket 2, 
however, applications should check for both WSAENOMORE and WSA_E_NO_MORE 
for the widest possible compatibility with Namespace Providers that use either one. 


Helper Functions 

e WSAGetServiceClassNameByClassid 
e WSAAddressToString 

e WSAStringToAddress 

e WSAGetServiceClassinfo 


The name resolution helper functions include a function to retrieve a service class name 
given a service class identifier, a pair of functions used to translate a transport address 
between a SOCKADDR structure and an ASCII string representation, a function to 
retrieve the service class schema information for a given service class, and a set of 
macros for mapping well known services to pre-allocated GUIDs. 


Chapter6 Winsock 2 API Overview 105 


The following macros from Winsock2.h aid in mapping between well known service 
classes and these namespaces. 


Macro Description 
SVCID_TCP(Port) Given a port for TCP/IP or UDP/IP or the 
SVCID_UDP(Port) object type in the case of Netware, returns 
SVCID_NETWARE(Object Type) the GUID (port number in host order). 
IS_SVCID_TCP(GUID) | Returns TRUE if the GUID is within the 
IS_SVCID_UDP(GUID) allowable range. 
IS_SVCID_NETWARE(GUID) 
SET_TCP_SVCID(GUID, port) Initializes a GUID structure with the GUID 
SET_UDP_SVCID(GUID, port) equivalent for a TCP or UDP port number 
(port number must be in host order). 
PORT_FROM_SVCID_TCP(GUID) _ Returns the port or object type associated 
PORT_FROM_SVCID_UDP(GUID) with the GUID (port number in host order). 


SAPID_FROM_SVCID_NETWARE(GUID) 


Name Resolution Data Structures 


There are several important data structures that are used extensively throughout the 
name resolution functions. These are described in the following. 


Query-Related Data Structures 


The WSAQUERYSET structure is used to form queries for A WSALoSmupServieeBadin, 
and used to deliver query results for WSALookupServiceNext. It is a complex structure 
since it contains pointers to several other structures, some of which reference still other 
structures. The relationship between WSAQUERYSET and the structures it references is 
illustrated in Figure 6-5. 


Within the WSAQUERYSET structure, most of the parameters are self explanatory, but 
some deserve additional explanation. The dwSize parameter must always be filled in 
with sizeof(WSAQUERYSET), as this is used by namespace providers to detect and 
adapt to different versions of the WSAQUERYSET structure that may appear over time. 


The dwOutputFlags parameter is used by a namespace provider to provide additional 
information about query results. For details, see WSALookupServiceNext. 


The WSAECOMPARATOR structure referenced by Ipversion i is used for both query 
constraint and results. For queries, the dwVersion parameter indicates the desired 
version of the service. The ecHow parameter is an enumerated type which specifies how 
the comparison can be made. The choices are COMP_EQUALS which requires that an 
exact match in version occurs, or COMP_NOTLESS which pial that the service’s 
version number be: no less than the value of dw Version. 
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The interpretation of dwNameSpace and IpNSProviderld depends upon how the 
structure is being used and is described further in the individual function descriptions 
that utilize this structure. | 


“WSAQUERYSET __ aad 


Service Instance Name 


_—| Service Class ID (GUID) | 
ae | 
—p|__WSAECOMPARATOR __| 
‘ipversion Cs dwVersion 7 
 ecHow (equals, or not less than) | 


IpNSProviderld 


- InafoProtocols 


lpszContext | ue Comment String 
dwNumberOfProtocols oe “ ss 


[dwNumberOfCsAddrs si 
foBlob 


AFPROTOCOLS 


were 


LocalAddr | 


, SOCKET_ADDRESS 


Pee 


SOCKADDR 


sa_family 


Figure 6-5: Data Structure Relationships. 


The /pszContext parameter applies to hierarchical namespaces, and specifies the 
starting point of a query or the location within the hierarchy where the service resides. 
The general rules are: | 


e A value of NULL, blank (*) Starts the search at the default context. 


e A value of “\” starts the search at the top of the namespace. 
e Any other value starts the search at the designated point. 


Providers that do not support containment may return an error if anything other than “ or 
‘\" is specified. Providers that support limited containment, such as groups, should 
accept “’, “\”, or a designated point. Contexts are namespace specific. If dwNameSpace 
is NS_ALL, then only “ or ‘\’ should be passed as the context since these are 
recognized by all namespaces. 
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The /pszQueryString parameter is used to supply additional, namespace-specific query 
information such as a string describing a well-known service and transport protocol 
name, as in “FTP/TCP”. 


The AFPROTOCOLS structure referenced by /IpafpProtocols is used for query purposes 
only, and supplies a list of protocols to constrain the query. These protocols are 
represented as (address family, protocol) pairs, since protocol values only have meaning 
within the context of an address family. 


The array of CSADDR_INFO structure referenced by /pcsaBuffer contain all of the 
information needed to for either a service to use in establishing a listen, or a client to use 
in establishing a connection to the service. The LocalAddr and RemoteAdadr parameters 
both directly containa SOCKET_ADDRESS structure. A service would create a socket 
using the tuple (LocalAdar.|pSockadadr->sa_family, iSocketType, a It would bind 
the socket to a local address using LocalAddr.|pSockaddr, and 
LocalAddr.|pSockaddrLength. The client creates its socket with the tuple 
(RemoteAdar.|pSockaddr->sa_family, iSocketType, iProtocol), and uses the combination 
of RemoteAddr.|pSockaddr, and RemoteAdar.|pSockaddrLength when making a remote 
connection. 


Service Class Data Structures 


When a new service class is installed, a WSASERVICECLASSINFO structure must be 
prepared and supplied. This structure also consists of substructures that contain a series 
of parameters that apply to specific namespaces. Figure 6-6 shows a class info data 
structure. 


WSASERVICECLASSINFO | 
lpServiceClassid 
dwCount Service Class Name 


3 


IpClassinfos eiceieceaeeta 


pashan nen aL 


WSANSGLASSINFO 
IpszName 

dwNameSpace 

dwValue Type. 
dwValueSize 

IpValue 


item Name 


a SOE Ee ESR RR RSE OE 


~ ftem Value 


Figure 6-6: Class Info Data Structure. 
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For each service class, there is a single WSASERVICECLASSINFO structure. Within 
the WSASERVICECLASSINFO structure, the service class’ unique identifier is contained 
in IpServiceClassl/d, and an associated display string is referenced by 
IpServiceClassName. This is the string that is returned by 
WSAGetServiceClassNameByClassld. 


The IpClassintos parameter in the WSASERVICECLASSINFO structure references an 
array of WSANSCLASSINFO structures, each of which supplies a named and typed 
parameter that applies to a specified namespace. Examples of values for the /oszName 
parameter include: “Sapld”, “TcpPort’, “UdpPort’, etc. These strings are generally 
specific to the namespace identified in dwNameSpace. Typical values for dwValueType 
might be REG_DWORD, REG_SZ, etc. The dwValueSize parameter indicates the length 
of the data item pointed to by /pValue. 


The entire collection of data represented ina WSASERVICECLASSINFO structure is 
provided to each namespace provider when WSAlnstallServiceClass is invoked. Each 
individual namespace provider then sifts through the list oo WSANSCLASSINFO 
structures and retains the information applicable to it. 


Compatible Name Resolution for TCP/IP in the Windows 
Sockets 1. 1 API 


Windows Sockets 1.1 defined a number of routines that were used for name resolution 
with TCP/IP (IP version 4) networks. These are customarily called the getXbyY functions 
and include the following. 


gethostname 
gethostbyaddr 
gethostbyname 
getprotobyname 
getprotobynumber 
getservbyname | 
getservbyport 


Asynchronous versions of these functions were also defined. 


WSAAsyncGetHostByAddr 
WSAAsyncGetHostByName 
WSAAsyncGetProtoByName 
WSAAsyncGetProtoByNumber 
WSAAsyncGetServByName 
WSAAsyncGetServByPort 


There are also two functions (now implemented in the Winsock2.dll) used to convert 
dotted Ipv4 internet address notation to and from string and binary representations, 
respectively. 


inet_addr 
inet_ntoa 
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All of these functions are specific to lpv4 TCP/IP networks and developers of protocol- 
independent applications are discouraged from continuing to utilize these transport- 
specific functions. However, in order to retain strict backward compatibility with Windows 
Sockets 1.1, all of the above functions continue to be supported as long as at least one 
namespace provider i is present that supports the AF_INET address family nee 
functions are not relevant to IP version 6, denoted by AF_INET6). 


~The Ws2_32.dll implements these compatibility functions in terms of the new, nfelowek 
independent name resolution facilities using an appropriate sequence of 
WSALookupServiceBegin/Next/End function calls. The details of how the getXbyY 
functions are mapped to name resolution functions are provided below. The 
WSs2_32.dll handles the differences between the asynchronous and synchronous 
versions of the getXbyY functions, so only the implementation of the synchronous 
getXbyY functions are discussed. 


Basic Approach for GetXbyY in the API 


Most getXbyY functions are translated by the Ws2_32.dll toa 
WSAServiceLookupBegin/Next/End sequence that uses one of a set of special GUIDs 
as the service class. These GUIDs identify the type of getXbyYoperation that is being 
emulated. The query is constrained to those NSPs that support AF_INET. Whenever a 
getXbyY function returns a hostent or servent structure, the Ws2_32.dll specifies the . 
LUP_RETURN_BLOB flag in WSALookupServiceBegin so that the desired information 
is returned by the NSP. These structures must be modified slightly in that the pointers 
contained within must be replaced with offsets that are relative to the start of the blob’s 
data. All values referenced by these pointer parameters must, of course, be completely _ 
contained within the blob, and all strings are ASCII. | 


getprotobyname and getprotobynumber Functions in the API 


These functions are implemented within the Ws2_32.DLL by consulting a local protocols 
_ database. They do not result in any name resolution query. 


getservbyname and getservbyport Functions in the API 


_ The WSALookupServiceBegin query uses SVCID_INET_ SERVICEBYNAME as the 
service class GUID. The /IpszServicelnstanceName parameter references a string which — 
indicates the service name or service port, and (optionally) the service protocol. The 
formatting of the string is illustrated as FTP or TCP or 21/TCP or just FTP. The string is 
not case sensitive. The slash mark, if present, separates the protocol identifier from the 
preceding part of the string. The Ws2_32.dll will specify LUP_RETURN_BLOB and the 
NSP will place a SERVENT structure in the blob (using offsets instead of pointers as 
described above). NSPs should honor these other LUP_RETURN_* flags as well. 
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Flag Description 


LUP_RETURN_NAME Returns the s_name parameter from SERVENT structure in 
IpszServiceInstanceName. 


LUP_LRETURN_TYPE Returns canonical GUID in /pServiceClassid It is understood 
| that a service identified as FTP or 21 may be on another port 
- according to locally established conventions. The s_port 
parameter of the SERVENT structure should indicate where 
the service can be contacted in the local environment. The 
canonical GUID returned when LUP_RETURN_TYPE is set 
should be one of the predefined GUIDs from Svcs.h that 
corresponds to the port number indicated in the SERVENT 
structure. — 


gethostbyname Function in the API 

The WSALookupServiceBegin query uses SVCID_INET_HOSTADDRBYNAME as the 
service class GUID. The host name is supplied in JoszService/nstanceName. The 
Ws2_32.DLL specifies LUP_RETURN_BLOB and the NSP places a HOSTENT structure 
in the blob (using offsets instead of pointers as described above). NSPs should honor 
these other LUP_RETURN_* flags as well. 


Flag — | Description 


LUP_RETURN_NAME _ Returns the h_name parameter from HOSTENT structure in 
| lpszServiceInstanceName. 
LUP_RETURN_ADDR Returns addressing information from HOSTENT in 
| CSADDR_INFO structures, port information is defaulted to 
zero. Note that this routine does not resolve host names that 
consist of a dotted internet address. 


gethostbyaddr Function in the API 

The WSALookupServiceBegin query uses SVCID_INET_HOSTNAMEBYADDR as the 
service class GUID. The host address is supplied in JoszServicelnstanceName as a 
dotted internet string (for example, “192.9.200.120”). The Ws2_32.DLL specifies 
LUP_RETURN_BLOB and the NSP places a HOSTENT structure in the blob (using 
offsets instead of pointers as described above). NSPs should honor these other 


_ LUP_RETURN_* flags as well. 


Flag | Description 


-LUP_RETURN_NAME _ Returns the h_name parameter from HOSTENT structure in 


lpszServicelnstanceName. 
LUP_RETURN_ADDR Returns addressing information from HOSTENT in 


CSADDR_INFO structures, port information is defaulted 
to zero. 
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gethostname Function in the API 


The WSALookupServiceBegin query uses SVCID_HOSTNAME as the service class 
GUID. If joszServiceinstanceName is NULL or references a NULL string (that is “”), the 
local host is to be resolved. Otherwise, a lookup on a specified host name occurs. For 
the purposes of emulating gethostname the Ws2_32.DLL specifies a null pointer for 
lpszServicelInstanceName, and specifies LUP_RETURN_NAME so that the host name is 
returned in the /pszServicelnstanceName parameter. If an application uses this query 
and specifies LUP_RETURN_ADDR then the host address is provided in a 
CSADDR_INFO structure. The LUP_RETURN_BLOB action is undefined for this query. 
Port information is defaulted to zero unless the /oszQueryString references a service 
such as FTP, in which case the complete transport address of the indicated service is 
supplied. | 


Multipoint and Multicast Semantics 


In considering how to support multipoint and multicast semantics in Windows Sockets 2 
a number of existing and proposed multipoint/multicast schemes (including IP-multicast, 
ATM point-to-multipoint connection, ST-II, T.120, H.320 (MCU), and so on) were 

— examined. While alike in some aspects, each is unlike in others. To enable a coherent 
discussion of the various schemes, it is valuable to first create a taxonomy that — 
characterizes the essential attributes of each. In this document, the term multipoint 
represents both multipoint and multicast. 


Multipoint Taxonomy 


The taxonomy described in this section first distinguishes the control plane that concerns 
itself with the way a multipoint session is established, from the data plane that eee with 
the transfer of data among session participants. 


In the control plane there are two distinct types of session establishment: rooted and 
nonrooted. In the case of rooted control, there exists a special participant, called c_root, 
that is different from the rest of the members of this multipoint session, each of which is 
— called a c_leaf. The c_root must remain present for the whole duration of the multipoint 
session, as the session is broken up in the absence of the c_root. The c_root usually 
initiates the multipoint session by setting up the connection to a c_leaf, or a number of 
c_leafs. The c_root may add more c_leafs, or (in some cases) a c_leaf can join the — 
c_root at a later time. Examples of the rooted control plane can be found in ATM 
and ST- Il. 


Fora noniooted control plane, all the members palonging. toa multipoint session are 
leaves, that is, no special participant acting as a c_root exists. Each c_leaf mustadd 
itself to a preexisting multipoint session that is always available (as in the case of an IP 
multicast address), or has been set up through some OOB mechanism which Is outside 
the scope of the Windows mia salcaaets 
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Another way to look at this is that a c_root still exists, but can be considered to be in the 
network cloud as opposed to one of the participants. Because a control root still exists, a 
nonrooted control plane could also be considered to be implicitly rooted. Examples for 
this kind of implicitly rooted multipoint schemes are: 


e A teleconferencing bridge. 
e The IP multicast system. 
e A Multipoint Control Unit (MCU) in a H.320 video conference. 


In the data plane, there are two types of data transfer styles: rooted and nonrooted. Ina 
rooted data plane, a special participant called d_root exists. Data transfer only occurs 
between the d_root and the rest of the members of this multipoint session, each of which 
is referred to as a d_leaf. The traffic could be unidirectional or bi-directional. The data 
sent out from the d_root is duplicated (if required) and delivered to every d_leaf, while 
the data from d_leafs only goes to the d_root. In the case of a rooted data plane, no 
traffic is allowed among d_leafs. An example of a protocol that is rooted in the data 
plane is ST-ll. 


In a nonrooted data plane, all the participants are equal, that is, any data they send is 
delivered to all the other participants in the same multipoint session. Likewise each 
d_leaf node can receive data from all other d_leafs, and in some cases, from other 
nodes that are not participating in the multipoint session. No special d_root node exists. 
IP-multicast is nonrooted in the data plane. 


Note that the question of where data unit duplication occurs, or whether a shared single 
tree or multiple shortest-path trees are used for multipoint distribution are protocol 
issues, and irrelevant to the interface the application would use to perform multipoint 
communications. Therefore these issues are not addressed in this appendix or the 
Windows Sockets interface. 


The following table depicts the taxonomy described above and indicates how existing 
schemes fit into each of the categories. Note that there do not appear to be any existing 
schemes that employ a nonrooted control plane along with a rooted data plane. 


Nonrooted (implicit rooted) 
Rooted control plane control plane 


Rooted data plane ATM, ST-II No known examples. 
Nonrooted data plane —iT..120 IP-multicast, H.320 (MCU) 


Windows Sockets 2 interlace Elements for Multipoint and 
Multicast 


The mechanisms that have been incorporated into Windows Sockets 2 for utilizing 
multipoint capabilities can be summarized as follows: 


Three attribute bits in the WSAPROTOCOL_INFO structure. 
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e Four flags defined for the dwFlags parameter of WSASocket. 
e One function, WSAJoinLeaf, for adding leaf nodes into a multipoint session. 


e Two WSAloctl command codes for controlling multipoint loopback and the scope of 
multicast transmissions. 


The following paragraphs describe these interface elements in more detail: 


e Semantics for Joining Multipoint Leaves 
e How Existing Multipoint Protocols Support These Extensions 


Attributes in WSAPROTOCOL INFO Structure 


In support of the taxonomy described above, three attribute parameters in the 
WSAPROTOCOL_INFO structure are use to distinguish the schemes used in the control 
and data planes respectively: 


e XP1_SUPPORT_MULTIPOINT with a value of 1 indicates this protocol entry supports © 
multipoint communications, and that the following two parameters are meaningful. 


e XP1_MULTIPOINT_CONTROL_ PLANE indicates whether the control plane is rooted 
(value = 1) or nonrooted (value = 0). 


e XP1_MULTIPOINT_DATA_PLANE indicates whether the data plane is rooted 
(value = 1) or nonrooted (value = 0). 


Note that two WSAPROTOCOL_INFO entries would be present if a multipoint protocol 
supported both rooted and nonrooted data planes, one entry for each. | 


The application can use WSAEnumProtocols to discover whether multipoint 
communications is supported for a given protocol and, if so, how it is supported with 
respect to the control and data planes, respectively. 


Flag Bits for WSASocket 


In some instances sockets joined to a multipoint session may fale some behavioral 
differences from point-to-point sockets. For example, a d_leaf socket in a rooted data 
plane scheme can only send information to the d_root participant. This creates a need 
for the application to be able to indicate the intended use of a socket coincident with its 
creation. This is done eg four-flag bits that can be set in the EW is9° parameter 
to WSASocket: | | 


e WSA_FLAG_MULTIPOINT_C_ROOT, for the creation of a socket acting as a c_root, 
_and only allowed if a rooted control plane is indicated in the rele 
WSAPROTOCOL_INFO entry. 

e WSA_FLAG_MULTIPOINT_C_ LEAF, for the creation of a socket acting as a C_leaf, 

~ and only allowed if XP1 _SUPPORT_ MULTIPOINT is indicated in the corresponding 

WSAPROTOCOL... INFO aay: 
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e WSA_FLAG_MULTIPOINT_D_ROOT, for the creation of a socket acting as a d_root, 
and only allowed if a rooted data plane is indicated in the corresponding 
WSAPROTOCOL_INFO entry. 


© WSA_FLAG_MULTIPOINT_D_LEAF, for the creation of a socket acting as a d_leaf, 
and only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the corresponding 
WSAPROTOCOL_INFO entry. 


Note that when creating a multipoint socket, exactly one of the two control-plane flags, 
and one of the two data-plane flags must be set in WSASocket’s dwFlags parameter. 
Thus, the four possibilities for creating multipoint sockets are: 


e “c_root/d_root” 
e “c_root/d_leaf’ 
e “c_leaf/d_root” 
e “c_leaf /d_leaf 


SIO_MULTIPOINT_LOOPBACK Command Code for WSAloctl © 


When d_leaf sockets are used in a nonrooted data plane, it is desirable to have traffic 
that is sent out received back on the same socket. The SIO_MULTIPOINT_LOOPBACK 
command code for WSAloctl is used to enable or disable loopback of multipoint traffic. 


SIO_MULTICAST SCOPE Command Code for WSAloct! 


When multicasting is employed, it is usually necessary to specify the scope over which 
the multicast should occur. Scope is defined as the number of routed network segments 
to be covered. A scope of zero would indicate that the multicast transmission would not 
be placed on the wire but could be disseminated across sockets within the local host. A 
scope value of one (the default) indicates that the transmission will be placed on the 
wire, but will not cross any routers. Higher scope values determine the number of routers 
that may be crossed. Note that this corresponds to the time-to-live (TTL) parameter in IP 
multicasting. | 


The function WSAJoinLeaf is used to join a leaf node into the multipoint session. see 
the following for a discussion on how this function is utilized. 


Semantics for Joining Multipoint Leaves 


In the following, a multipoint socket is frequently described by defining its role in one of 
the two planes (control or data). It should be understood that this same socket has a role 
in the other plane, but this is not mentioned in order to keep the references short. For 
example when a reference is made to a “c_root socket”, this could be either a 
c_root/d_root or a c_root/d_leaf socket. | 


In rooted control plane schemes, new leaf nodes are added to a multipoint session in 
one or both of two different ways. In the first method, the root uses WSAJoinLeaf to 
initiate a connection with a leaf node and invite it to become a participant. On the leaf 
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node, the peer application must have created a c_leaf socket and used listen to set it 
into listen mode. The leaf node receives an FD_ACCEPT indication when invited to join 
the session, and signals its willingness to join by calling WSAAccept. The root 
application then receives an FD_CONNECT indication when the join operation has been 
completed. 


In the second method, the roles are essentially reversed. The root application creates a 
c_root socket and sets it into listen mode. A leaf node wishing to join the session creates 
a C_leaf socket and uses WSAJoinLeaf to initiate the connection and request 
admittance. The root application receives FD_ACCEPT when an incoming admittance 
request arrives, and admits the leaf node by calling WSAAccept. The leaf node receives 
FD_CONNECT when it has been admitted. 


In a nonrooted control plane, where all nodes are c_leaf’s, the WSAJoinLeaf is used to 
initiate the inclusion of a node into an existing multipoint session. An FD_CONNECT 
indication is provided when the join has been completed and the returned socket 
descriptor is useable in the multipoint session. In the case of IP multicast, this would 
correspond to the IP_ADD_MEMBERSHIP socket option. 


(Readers familiar with IP multicast’s use of the connectionless UDP protocol may be 
concerned by the connection-oriented semantics presented here. In particular the notion 
of using WSAJoinLeaf on a UDP socket and waiting for an FD_CONNECT indication 
may be troubling. There is, however, ample precedent for applying connection-oriented 
semantics to connectionless protocols. It is allowed and sometimes useful, for example, 
to invoke the standard connect function on a UDP socket. The general result of applying 
connection-oriented semantics to connectionless sockets is a restriction in how such | 
sockets may be used, and this is the case here, as well. A UDP socket used in | 
WSAJoinLeaf will have certain restrictions, and waiting for an FD_CONNECT indication 
(which in this case simply indicates that the corresponding IGMP message has been 
sent) is one such limitation.) 


There are therefore, three instances where an application would use WSAJoinLeaf: 


e Acting as a multipoint root and inviting a new leaf to join the session 
e Acting as a leaf making an admittance request to a rooted multipoint session 


e Acting as a leaf seeking admittance to a nonrooted multipoint session fOr example, IP 
multicast) 


Using WSAJoinLeaf 


As mentioned previously, the function WS<AJoinLeaf is used to join a leaf node into a 
multipoint session. WSAJoinLeaf has the same parameters and semantics as) 
WSAConnect except that it returns a socket descriptor (as in WSAAccept), and it has 
an additional dwFlags parameter. The dwFlags parameter is used to indicate whether 
the socket will be acting only as a sender, only as a receiver, or both. Only multipoint 
sockets may be used for input parameter s in this function. If the multipoint socket is in 
nonblocking mode, the returned socket descriptor is not useable until after a 
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corresponding FD_CONNECT indication is received. A root application in a multipoint 
session may call WSAJoinLeaf one or more times in order to add a number of leaf 
nodes, however at most one multipoint connection request may be outstanding at a time. 


The socket descriptor returned by WSAJoinLeaf is different depending on whether the 
input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the 
name parameter designates a particular leaf node to be added and the returned socket 
descriptor is a c_leaf socket corresponding to the newly added leaf node. It is not 
intended to be used for the exchange of multipoint data, but rather is used to receive 
FD_XXX indications (for example, FD_CLOSE) for the connection that exists to the 
particular c_leaf. Some multipoint implementations may also allow this socket to be used 
for side chats between the root and an individual leaf node. An FD_CLOSE indication is 
received for this socket if the corresponding leaf node calls closesocket to drop out of 


_ the multipoint session. Symmetrically, invoking closesocket on the c_leaf socket 


returned from WSAJoinLeaf causes the socket in the corresponding leaf node to get 
FD_CLOSE notification. 


When WSAJoinLeaf is invoked with a c_leaf socket, the name parameter contains the 
address of the root application (for a rooted control scheme) or an existing multipoint 
session (nonrooted control scheme), and the returned socket descriptor is the same as 
the input socket descriptor. In a rooted control scheme, the root application puts its 
c_root socket in listening mode by calling listen. The standard FD_ACCEPT notification 
is delivered when the leaf node requests to join itself to the multipoint session. The root 
application uses the usual accept/WSAAccept functions to admit the new leaf node. 
The value returned from either accept or WSAAccept is also a c_leaf socket descriptor 
just like those returned from WSAJoinLeaf. To accommodate multipoint schemes that 
allow both root-initiated and leaf-initiated joins, it is acceptable for a c_root socket that is 
already in listening mode to be used as in input to WSAJoinLeaf. 


A multipoint root application is generally responsible for the orderly dismantling of a 
multipoint session. Such an application may use shutdown or closesocket on a c_root 
socket to cause all of the associated c_leaf sockets, including those returned from 
WSAJoinLeaf and their corresponding c_leaf sockets in the remote leaf nodes, to get 
FD_CLOSE notification. 


semantic Differences Between Multipoint Sockets and 
Regular Sockets 


In the control plane, there are some significant semantic differences pétween a c_root 
socket and a regular point- -to- -point socket: 


e The c_root socket can be used in WSAJoinLeaf to join a new a leat. 


e Placing a c_root socket into listening mode (by calling listen) does not preclude the 
c_root socket from being used in a call to WSAJoinLeaf to add a new leaf, or for 
sending and receiving multipoint data. : 


e The closing of a c_root socket causes all of the associated c_leaf sockets to get 
FD_CLOSE notification. 
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There are no semantic differences between a c_leaf socket and a regular socket in the 
control plane, except that the c_leaf socket can be used in WSAJoinLeaf, and the use 
of c_leaf socket in listen indicates that only multipoint connection requests should be 
accepted. 


_In the data plane, the semantic differences between the d_root socket and a regular 
point-to-point socket are 


e The data sent on the d_ root socket is delivered to all the leaves in the same mampeunt 
session. 


_ @ The data received on the d_root socket may be from any of the leaves. 


The d_leaf socket in the rooted data plane has no semantic difference from the regular 
socket, however, in the nonrooted data plane, the data sent on the d_leaf socket goes to 
all the other leaf nodes, and the data received could be from any other leaf nodes. As © 
mentioned earlier, the information about whether the d_leaf socket is in a rooted or 
nonrooted data plane is contained in the corresponding WSAPROTOCOL_ INFO — 
structure for the socket. 


How Existing Multipoint P Protocols Support These Extensions 


In this section we indicate how IP multicast and ATM point-to-multipoint capabilities can 
be accessed through the Windows Sockets 2 multipoint functions. We chose these two 
as examples because they are popular and well understood. 


IP Multicast 


IP multicast falls into the category of nonrooted data plarie and nonrooted control plane. 
All applications play a leaf role. Currently, most IP multicast implementations use a set of 
— socket options proposed by Steve Deering to the IETF. Five operations are thus made 
available: 
e IP_MULTICAST_TTL—Sets time to live, controls scope of multicast session 
e IP_MULTICAST_IF—Determines interface to be used for multicasting. 
e IP_ADD_MEMBERSHIP—Joins a specified multicast session. 
e IP_DROP_MEMBERSHIP—Drops out of a multicast session. 
-@ IP_MULTICAST_LOOP—Controls loopback of multicast traffic. 


Setting the time-to-live for an IP multicast socket maps directly to using the 
SIO_MULTICAST_SCOPE command code for WSAloctI. 


The method for determining the IP interface to be used for multicasting is through a 
TCP/IP-specific socket option as described in the Windows Sockets 2 Protocol-Specific 

_ Annex. The remaining three operations are covered well with the Windows sockets 2 
semantics described here. 
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The application would open sockets with c_leaf/d_leaf flags in WSASocket. It would use 
WSAJoinLeaf to add itself to a multicast group on the default interface designated for 
multicast operations. If the flag in WSAJoinLeaf indicates that this socket is only a 
sender, then the join operation is essentially a no-op and no IGMP messages need to be 
sent. Otherwise, an IGMP packet is sent out to the router to indicate interests in 
receiving packets sent to the specified multicast address. Since the application created 
special c_leaf/d_leaf sockets used only for performing multicast, the standard | 
closesocket function would be used to drop out of the multicast session. The 
SIO_MULTIPOINT_LOOPBACK command code for WSAloctl provides a generic 
control mechanism for determining whether data sent on a d_leaf socket in a nonrooted 
multipoint scheme can also be received on the same socket. 


Note The Windows Sockets version of the IP_MULTICAST_LOOP option is 
semantically different than the UNIX version of the IP_MULTICAST_LOOP option. In 


‘Windows Sockets, the IP_MULTICAST_LOOP option applies only to the receive path. In 


contrast, the UNIX version of the IP_MULTICAST_LOOP option applies to the send 
path. For example, applications ON and OFF (which are easier to track than X and Y) 
join the same group on the same interface; application ON sets the 
IP_MULTICAST_LOOP option on, application OFF sets the IP_MULTICAST_LOOP 
option off. lf ON and OFF are Windows Sockets applications, OFF can send to ON, but 
ON cannot sent to OFF. In contrast, if ON and OFF are UNIX applications, ON can send 
to OFF, but OFF cannot send to ON. 


ATM Point to Multipoint 

ATM falls into the category of rooted data and rooted control planes. An application 
acting as the root would create c_root sockets and counterparts running on leaf nodes 
would utilize c_leaf sockets. The root application uses WSAJoinLeaf to add new leaf 
nodes. The corresponding applications on the leaf nodes will have set their c_leaf 
sockets into listen mode. WSAJoinLeaf with a c_root socket specified is mapped to the 
Q.2931 ADDPARTY message. The leaf-initiated join is not supported in ATM UNI 3.1, 
but is supported in ATM UNI 4.0. Thus WSAJoinLeaf with a c_leaf socket specified is 
mapped to the appropriate ATM UNI 4.0 message. 


There are additional considerations to bear in mind for ATM point-to-multipoint: 


e The addition of new leaves to the ATM point-to-multipoint session is invitation-based 
only. The root invites leaves—which have already their accept function call—by 
calling the WSAJoinLeaf function. 

e The flow of data in an ATM point-to-multipoint session is from root-to-leaves only; 
leaves cannot use the same session to send information to the root. 


e Only one leaf per ATM adapter is allowed. 
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Additional Windows Socket Information 


This section contains information on the Windows Sockets 2 header file, additional 
Windows Sockets reference material, and the error codes encountered in programming 
for Windows Sockets 2. 


Windows Sockets 2 API Header File—Winsock2.h 


New versions of Winsock2.h will appear periodically as new identifiers are allocated by 
the Windows Sockets Identifier Clearinghouse. The clearinghouse can be reached 
through the world wide web at: 


http://www.stardust.com/winsock/ 


Socket Options Specific to Microsoft Service Providers 


Microsoft's service providers support additional socket options not included in the 
Windows Sockets 2 API: 


Socket Option for Windows NT 4.0 Only 
Socket Option for Windows NT 4.0 and Windows 95 


Socket Option for Windows NT 4.0 Only 


The following socket options are Microsoft-specific extensions for connect and 
disconnect data and options, and are used only by non-TCP/IP transports such as 

DECNet, OSI TP4, etc. These are only used in the Microsoft implementation of Windows 

Sockets on Windows NT 4.0. 

e SO_CONNDATA 

¢ SO_CONNOPT 

e SO_DISCDATA 

e SO_DISCOPT 

e SO_CONNDATALEN 

e SO_CONNOPTLEN 

e SO_DISCDATALEN 

e SO_DISCOPTLEN | 

The following socket options are Microsoft-specific extensions for controlling the size of 

datagrams: 7 eye +e re ae 

e SO_MAXDG | 

e SO_MAXPATHDG 
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for Windows NT 4.0 and Windows 95 


Socket Option 
SO_SNDTIMEO 


SO RCVTIMEO 


Details on SO. SNDTIMEO and SO RCVTIMEO 


These two options set up time-outs for the send, sendto, recv, and recvfrom functions. 


You can obtain the same functionality by calling select with a time-out just before the I/O 
call, but these options offer a significant improvement in performance by avoiding a 
kernel transition and the other overhead of the select call. For any code whose 
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substitute SO. RCVTIMEO for SO_SNDTIMEO 


The TIMEOQUT_VALUE is the needed time-out 


After setting one of these options to a nonzero value, I/O through the Windows Sockets 


calls fails with the error WSAETIMEDOUT if the request cannot be satisfied within the 
specified time-out. If a request times out, an application has no guarantees as to how 


much data was actually sent or received in the I/O call. 
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Additional Documentation 


This specification is intended to cover the Windows Sockets interface in detail. Many 
details of specific protocols and Windows, however, are intentionally omitted in the 
interest of brevity, and this specification often assumes background knowledge of these 
topics. For more information, the following references may be helpful: 


Networking Books 


Jones, A. and Ohlund, J., Network Programming for Microsoft Windows, (Microsoft 
Press, 1999). 


Braden, R.[1989], RFC 1122, Requirements for Internet Hosts--Communication Layers, 
Internet Engineering Task Force. 


Comer, D., Internetworking with TCP/AP Volume I: Principles, Protocols, and 
Architecture, (Prentice Hall, 1991). 


Comer, D. and Stevens, D., Internetworking with TCP/IP Volume II: Design, 
Implementation, and Internals (Prentice Hall, 1991). 


Comer, D. and Stevens, D., Internetworking with TCP/IP Volume Il Client-Server 
_ Programming and Applications (Prentice Hall, 1991). 


Leffler, S. et al., An Advanced 4.3BSD Interprocess Communication Tutorial. 
Stevens, W.R., Unix Network Programming (Prentice Hall, 1990). | 

Stevens, W.R.. TCP/IP Illustrated, Volume 1: The Protocols (Addison-Wesley, 1994). 
Wright, G.R. and Stevens, W.R., TCP/IP Illustrated Volume 2: The Implementation 
(Addison-Wesley, 1995). 


Windows Sockets Books 


Jones, A. and Ohlund, J., Network Programming for Microsoft Windows (Microsoft 
Press, 1999). 


Bonner, P., Network Programming with Windows Sockets (Prentice Hall, 1995). 
Dumas, A., Programming Windows Sockets (Sams Publishing, 1995). 


Quinn, B. and Shute, D., Windows Sockets Network epograninng ge Wesley, 
1995). | 


Roberts, D., Developing for the Internet with Winsock (Coriolis Group Books, 1995). 
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Error Codes in the Winsock API 


The following is a list of possible error codes returned by the WSAGetLastError call, 
along with their extended explanations. Errors are listed in alphabetical order by error 
macro. Some error codes defined in Winsock2.h are not returned from any function— 
these are not included in this topic. 


Error Codes 


WSAEACCES 
(10013) 


Permission denied. 
An attempt was made to access a Sonkett in a way forbidden by its access 
permissions. An example is using a broadcast address for sendto without 
broadcast permission being set using setsockopt(SO_BROADCAST). 


Another possible reason for the WSAEACCES error is that when the bind function — 
~ is called (on Windows NT 4 SP4 or later), another application, service, or kernel 

mode driver is bound to the same address with exclusive access. Such exclusive 

access is a new feature of Windows NT 4 SP4 and later, and is implemented 

by using the SO_ EXCLUSIVEADDRUSE option. 


WSAEADDRINUSE 
(10048) 


Address already in use. _ 
Typically, only one usage of each socket address (protocol/IP address/port) is 
permitted. This error occurs if an application attempts to bind a socket to an 
IP address/port that has already been used for an existing socket, or a socket that 
wasn’t closed properly, or one that is still in the process of closing. For server 
applications that need to bind multiple sockets to the same port number, consider 

using setsockopt(SO_REUSEADDR). Client applications usually need not call 

_ bind at all—connect chooses an unused port automatically. When bind is called 
with a wildcard address (involving ADDR_ANY), a WSAEADDRINUSE error could 
be delayed until the specific address is committed. This could happen with a call to 
another function later, including connect, listen, WSAConnect, or WSAJoinLeaf. 
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WSAEADDRNOTAVAIL 
(10049) 


Cannot assign requested address. 
The requested address is not valid in its context. This normally results from an 
attempt to bind to an address that is not valid for the local machine. This can also 
result from connect, sendto, WSAConnect, WSAJoinLeaf, or WSASendTo 
when the remote address or port is not valid for a remote machine (for example, 
address or port 0). 


WSAEAFNOSUPPORT 
(10047) 


Address family not supported by protocol family. 
An address incompatible with the requested protocol was used. All sockets are 
created with an associated address family (that is, AF_INET for Internet Protocols) 
and a generic protocol type (that is, SOCK_STREAM). This error is returned if an 
incorrect protocol is explicitly requested in the socket call, or if an address of the 
wrong family is used for a socket, for example, in sendto. 

WSAEALREADY 
(10037) 


_ Operation already in progress. 
An operation was attempted on a nonblocking socket with an operation already in 
progress—that is, calling connect a second time on a nonblocking socket that is 
already connecting, or canceling an asynchronous request (WSAAsyncGetXbyY) 
that has already been canceled or completed. 


WSAECONNABORTED 
(10053) 


Software caused connection abort. | 
An established connection was aborted by the software in your host machine, 
possibly due to a data transmission time-out or pigwee error. 


WSAECONNREFUSED 
(10061) 


Connection refused. 
No connection could be made because the target mecning actively refused it. 
This usually results from trying to connect to a service that is inactive on the foreign 
host—that is, one with no server application running. 
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WSAECONNRESET 
(10054) 


Connection reset by peer. 
An existing connection was forcibly closed by the remote host. This normally 
results if the peer application on the remote host is suddenly stopped, the host 
is rebooted, or the remote host uses a hard close (see setsockopt for more 
information on the SO_LINGER option on the remote socket.) This error may also 
result if a connection was broken due to keep-alive activity detecting a failure while 
one or more operations are in progress. Operations that were in progress fail with 
WSAENETRESET. Subsequent operations fail with WSAECONNRESET. 


WSAEDESTADDRREQ 
(10039) 


Destination address required. 
A required address was omitted from an operation on a socket. For example, this 
error is returned if sendito | is called with the remote address of ADDR_ANY. 


WSAEFAULT 
(10014) 


Bad address. 
| The system detected an invalid pointer address in attempting to use a pointer 
argument of a call. This error occurs if an application passes an invalid pointer 
value, or if the length of the buffer is too small. For instance, if the length of an 
argument, which is a SOCKADDR structure, is smaller than the size’ 
of (SOCKADDR). 


WSAEHOSTDOWN 
(10064) 


Host is down. 
A socket operation failed because the destination host is down. A socket operation 
encountered a dead host. Networking activity on the local host has not been 
initiated. These conditions are more likely to be indicated by the error 
WSAETIMEDOUT. | 


~ WSAEHOSTUNREACH 
(10065) 


No route to host. | 
_ Asocket operation was attempted to an unreachable host. See 
WSAENETUNREACH. 


WSAEINPROGRESS 
— (10036) 
Operation now in progress. 
A blocking operation is currently BxOcutina: Windows Sockets ont allows a single 
blocking operation—per task or thread—to be outstanding, and if any other function 
call is made (whether or not it references that or any other socket) the function fails 
with the WSAEINPROGRESS error. 
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WSAEINTR 
(10004) 


Interrupted function call. 
A blocking operation was interrupted oda a Call to WSACancelBlockingCall. 


WSAEINVAL 
~ (10022) 


Invalid argument. 
Some invalid argument was supplied (for example, specifying an invalid level to the 
setsockopt function). In some instances, it also refers to the current state of the 
socket—for instance, calling accept on a socket that is not listening. 


WSAEISCONN 
(10056) 


Socket is already connected. 
A connect request was made on an already-connected socket. Some 
implementations also return this error if sendto is called on a connected 
SOCK_DGRAM socket (for SOCK_STREAM sockets, the fo parameter in sendto 
is ignored) although other implementations treat this as a legal occurrence. 


WSAEMFILE 
(10024) 
Too many open files. 
~ Too many open sockets. Each implementation may have a maximum number of 
socket handles available, either globally, per pieces or per thread. | 


WSAEMSGSIZE 
(10040) 


Message too long. 
A message sent on a datagram socket was larger than the internal message buffer 
or some other network limit, or the buffer used to receive a datagram was smaller 
than the datagram itself. 


WSAENETDOWN 
(10050) 


Network is down. 7 
A socket operation encountered a dead newwone This could indicate a serious 
failure of the network system (that is, the protocol stack that the Windows Sockets 
DLL runs over), the network interface, or the local network itself. 


WSAENETRESET 
(10052) 


Network dropped connection on reset. 
The connection has been broken due to keep- -alive activity detecting a failure while 
the operation was in progress. It can also be returned by setsockopt if an attempt 
is made to set SO_KEEPALIVE on a connection that has already failed. 
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WSAENETUNREACH 
(10051) 


Network is unreachable. 
A socket operation was attempted to an unreachable network. This usually means 
the local software knows no route to reach the remote host. 


WSAENOBUFS 
(10055) 


No buffer space available. 
An operation on a socket could not be performed because the system lacked 
sufficient buffer space or because a queue was full. 


WSAENOPROTOOPT 
(10042) 


Bad protocol option. 
An unknown, invalid or unsupported option or level was specified ina gotenencr 
or setsockopt call. : 


WSAENOTCONN 
(10057) 


Socket is not connected. - : 
A request to send or receive data was disallowed because the socket is not 
connected and (when sending on a datagram socket using sendto) no address 
was supplied. Any other type of operation might also return this error—for example, 
setsockopt setting SO_ See if the connection has been reset. 


-WSAENOTSOCK 
(10038) 


Socket operation on nonsocket. 
An operation was attempted on something that is not a socket. Either the socket 
handle parameter did not reference a valid socket, or for select, a member of an 
fd_set was not valid. | } ; | 


WSAEOPNOTSUPP 
(10045) 


Operation not supported. 
The attempted operation is not supported for the type of object feferenced Usually 
this occurs when a socket descriptor to a socket that cannot support this operation 
is trying to accept a connection on a eae socket. 


WSAEPFNOSUPPORT 
(10046) 


Protocol family not supported. 
The protocol family has not been contoured into the system or no implementation 
for it exists. This message has a slightly different meaning from 

~ WSAEAFNOSUPPORT. However, it is interchangeable in most cases, and all 
Windows Sockets functions that return one of these messages also specify 
WSAEAFNOSUPPORT. 
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WSAEPROCLIM 
(10067) 
Too many processes. 
A Windows Sockets implementation may have a limit on the number of applications 
that can use it simultaneously. WSAStartup may fail with this error if the limit has 
been reached. 


WSAEPROTONOSUPPORT 
(10043) 


Protocol not supported. 
The requested protocol has not been configured into the system, or no 
implementation for it exists. For example, a socket call requests a SOCK_DGRAM 
socket, but specifies a stream protocol. 


WSAEPROTOTYPE 
(10041) 


Protocol wrong type for socket. 
A protocol was specified in the socket function call that does not support the 
semantics of the socket type requested. For example, the ARPA Internet UDP 
protocol cannot be specified with a socket type of SOCK_STREAM. 


WSAESHUTDOWN 
(10058) 


Cannot send after socket shutdown. 
A request to send or receive data was disallowed because the socket had already 
been shut down in that direction with a previous shutdown call. By calling 
shutdown a partial close of a socket is requested, which is a signal that sending or 
receiving, or both have been discontinued. 


WSAESOCKTNOSUPPORT 
(10044). | 


Socket type not supported. 
The support for the specified socket type does not exist in this address family. For 
example, the optional type SOCK_RAW might be selected in a socket call, and the 
implementation does not support SOCK_RAW sockets at all. 


WSAETIMEDOUT 
(10060) 


Connection timed out. | oa" 
A connection attempt failed because the connected party did not properly respond 
after a period of time, or the established connection failed because the connected 
host has failed to respond. 


WSATYPE_NOT_FOUND 
(10109) 


Class type not found. 
The specified class was not found. 
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WSAEWOULDBLOCK 
(10035) 


Resource temporarily unavailable. 
This error is returned from operations on nonblocking sockets that cannot be 
completed immediately, for example recv when no data is queued to be read from 
the socket. It is a nonfatal error, and the operation should be retried later. It is 
normal for WSAEWOULDBLOCK to be reported as the result from calling connect 
on a nonblocking SOCK_STREAM socket, since some time must elapse for the 
connection to be established. 


WSAHOST_NOT_FOUND 
(11001) 


Host not found. 
No such host is known. The name is not an official host name or alias, or it cannot 
be found in the database(s) being queried. This error may also be returned for 
protocol and service queries, and means that the specified name could not be 
found in the relevant database. 
WSA_INVALID_HANDLE 
(OS dependent) 


Specified event object handle is invalid. 
An application attempts to use an event object, but the specified handle i is not valid. 


WSA_INVALID_PARAMETER 
(OS dependent) — 


One or more parameters are invalid. 3 
_ An application used a Windows Sockets function which directly maps to a Win32 
function. The Win32 function is indicating a problem with one or more parameters. 


WSAINVALIDPROCTABLE 
(OS dependent) 


Invalid procedure table from service provider. 
A service provider returned a bogus procedure table to Ws2_32.dll. (Usually 
caused by one or more of the function pointers being null.) 


WSAINVALIDPROVIDER 
_ (OS dependent) 


Invalid service provider version punber 
A service provider returned a version number other than 2.0. 


WSA_IO_INCOMPLETE 
(OS dependent) 


-Overlapped I/O event object not in signaled state. 
The application has tried to determine the status of an overlapped operation which 
is not yet completed. Applications that use WSAGetOverlappedResult (with the 
fWait flag set to FALSE) in a polling mode to determine when an overlapped 
operation has completed, get this error code until the operation is complete. 
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WSA_IO_PENDING 
(OS dependent) 


Overlapped operations will complete later. | 
The application has initiated an overlapped operation that cannot be completed 
immediately. A eae indication will be given later when the operation has 
been completed. 


WSA_NOT_ENOUGH_MEMORY 
(OS dependent) 


Insufficient memory available. 
An application used a Windows Sockets function that directly maps to a Win32 
function. The Win32 function is indicating a lack of required memory resources. 


WSANOTINITIALISED 
(10093) 


Successful WSAStartup not yet performed. 
Either the application hasn’t called WSAStartup or WSAStartup failed. The 
application may be accessing a socket that the current active task does not own 
(that is, trying to share a socket between tasks), or WSACleanup has been called 
too many times. 


WSANO_DATA 
(11004) 


Valid name, no data record of requested type. 
The requested name is valid and was found in the database, but it does not have 
the correct associated data being resolved for. The usual example for this is a host 
name-to-address translation attempt (using gethostbyname or 
WSAAsyncGetHostByName) which uses the DNS (Domain Name Server). An 
MX record is returned but no A record—indicating the host itself exists, but is not 
directly reachable. 


WSANO_RECOVERY 
(11003) 


_ This is a nonrecoverable error. 
This indicates some sort of nonrecoverable error occurred during a database 
lookup. This may be because the database files (for example, BSD-compatible 
HOSTS, SERVICES, or PROTOCOLS files) could not be found, or a DNS request 
was returned by the server with a severe error. 
WSAPROVIDERFAILEDINIT 
(OS dependent) 
Unable to initialize a service provider. 


Either a service provider's DLL could not be loaded (LoadLibrary failed) or the 
provider's WSPStartup/NSPStartup function failed. 
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WSASYSCALLFAILURE 
(OS dependent) 


System call failure. 
Returned when a system call that should never fail does. For example, if a call to 
WaitForMultipleObjects fails or one of the registry functions fails trying to 
manipulate the protocol/name space catalogs. 


WSASYSNOTREADY 
(10091) 


Network subsystem is unavailable. 
This error is returned by WSAStartup if the Windows Sockets implementation 
cannot function at this time because the underlying system it uses to provide 
network services is currently unavailable. Users should check: 


e That the appropriate Windows Sockets DLL file is in the current path. 


e That they are not trying to use more than one Windows Sockets 
implementation simultaneously. If there is more than one Winsock DLL on your 
system, be sure the first one in the path is appropriate for the network 
subsystem currently loaded. 


e The Windows Sockets implementation documentation to be sure all necessary 
components are currently installed and configured correctly. 


WSATRY_AGAIN 
(11002) 


Nonauthoritative host not found. 
This is usually a temporary error during host name resolution and means that the 
local server did not receive a response from an authoritative server. A retry at 
some time later may be successful. | | 


WSAVERNOTSUPPORTED 
(10092) 


Winsock.dll version out of range. 

The current Windows Sockets implementation does not support the Windows — 
Sockets specification version requested by the application. Check that no old 
Windows Sockets DLL files are being accessed. 

WSAEDISCON | 

(10101) 

Graceful shutdown in progress. | 
Returned by WSARecv and WSARecvF rom to indicate that the remote party has 
initiated a graceful shutdown sequence. 

WSA_OPERATION_ABORTED 

(OS dependent) 

Overlapped operation aborted. 

An overlapped operation was canceled due to the closure of the socket, or the 
execution of the SIO_LFLUSH command in WSAloctl. 
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Winsock 2 Functions 


Windows Sockets 2 Functions 


accept — 


The Windows Sockets accept function permits an incoming connection attempt on a 
socket. | 


Parameters 
S 


[in] Descriptor identifying a socket that has been placed in a listening state with the 
listen function. The connection is actually made with the socket that is returned by 
accept. | | 


addr 
[out] Optional pointer to a buffer that receives the address of the connecting entity, as 
known to the communications layer. The exact format of the addr parameter is 
determined by the address family established when the socket was created. 


addrlen | 
[out] Optional pointer to an integer that contains the length of addr. 


Return Values 


lf no error occurs, accept returns a value of type SOCKET that is a descriptor for the 
new socket. This returned value is a handle for the socket on which the actual 
connection is made. 


Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be 
retrieved by calling WSAGetLastError. 


The integer referred to by adarlen initially contains the amount of space pointed to by 
addr. On return it will contain the actual length in bytes of the address returned. 
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Remarks 


The accept function extracts the first connection on the queue of pending connections 
on socket s. It then creates a new socket and returns a handle to the new socket. The 
newly created socket is the socket that will handle the actual connection and has the 
same properties as socket s, including the asynchronous events registered with the 
WSAAsyncSelect or WSAEventSelect functions. 


The accept function can block the caller until a connection is present if no pending 
connections are present on the queue, and the socket is marked as blocking. If the 
socket is marked as nonblocking and no pending connections are present on the queue, 
accept returns an error as described in the following. After the successful completion of 
accept returns a new socket handle, the accepted socket cannot be used to accept 
more connections. The original socket remains open and listens for new connection 
requests. 


The parameter addr is a result parameter that is filled in with the address of the 
connecting entity, as known to the communications layer. The exact format of the addr 
parameter is determined by the address family in which the communication is occurring. 
The adadrlen is a value-result parameter; it should initially contain the amount of space 
pointed to by addr, on return it will contain the actual length (in bytes) of the address 
returned. , | 


The accept function is used with connection- ‘oriented socket types such as_ 
SOCK_STREAM. 


If addr and/or addrlen are equal to NULL, then no information about the remote address 
of the accepted socket is returned. 


Error Codes 

Error code Meaning | 

WSANOTINITIALISED A successful WSAStartup call must occur before using 

sb this function. 
WSAENETDOWN The network subsystem has failed. 
WSAEFAULT The addrlen parameter is too small or addr is not a valid 
part of the user address space. | 

WSAEINTR A blocking Windows Sockets 1.1 call was canceled 
an — through WSACancelBlockingCall. 

WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress, or the 
| service provider is still processing a callback function. 

WSAEINVAL The listen function was not invoked prior to accept. 

WSAEMFILE : The queue is nonempty upon entry to accept and there 


are no descriptors available. 
WSAENOBUFS No buffer space is available. 
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Error code Meaning 
WSAENOTSOCK The descriptor is not a socket. 
WSAEOPNOTSUPP _ The referenced socket is not a type that supports 
| connection-oriented service. 
WSAEWOULDBLOCK The socket is marked as nonblocking and no connections 


are present to be accepted. 


Notes for ATM 


The following are important issues associated with connection setup, and must be 
considered when using Asynchronous Transfer Mode (ATM) with Windows Sockets 2: 


e The accept and WSAAccept functions do not necessarily set the remote address 
- and address length parameters. Therefore, when using ATM the caller should use the 
WSAAccept function and place ATM_CALLING_PARTY_NUMBEF__IE in the 
ProviderSpecific member of the QOS structure, which itself is included in the 
IpDSQOS parameter of the callback function used in accordance with WSAAccept. 


e When using the accept function, realize that the function may return before 
connection establishment has traversed the entire distance between sender and 
receiver. This is because the accept function returns as soon as it receives a 
CONNECT ACK message; in ATM a CONNECT ACK message is returned by the 
next switch in the path as soon as a CONNECT message is processed (rather than 
the CONNECT ACK being sent by the end node to which the connection is ultimately 
established). As such, applications should realize that if data is sent immediately 

_ following receipt of a CONNECT ACK message, data loss is possible, since the 
connection may not have been established “all the way” between sender and receiver. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
_ Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, bind, 
connect, listen, select, socket, WSAAsyncSelect, WSAAccept 


AcceptEx 
The Windows Sockets AcceptEx function accepts a new connection, returns the local 


~ and remote address, and receives the first block of data sent by the client application. 
_ The AcceptEx function is not aati on Windows 95/98. 


136 Volume 1 Winsock and QOS 


Note This function is a Microsoft-specific extension to the Windows Sockets - 
specification. For more information, see Microsoft Extensions and Windows Sockets 2 2. 


Parameters 


sListenSocket | | 
[in] Descriptor identifying a socket that has already been called with the listen 
function. A server application waits for attempts to connect on this socket. 


sAcceptSocket | 
[in] Descriptor identifying a socket on which to accept an incoming connection. This 
socket must not be bound or connected. 


/pOutputBuffer 
[in] Pointer to a buffer that receives the first block of data sent on a new connection, 
the local address of the server, and the remote address of the client. The receive data 
is written to the first part of the buffer starting at offset zero, while the addresses are 
written to the latter part of the buffer. If this parameter is set to NULL, no receive will 
be performed, nor will local or remote addresses be available through the use of 
GetAcceptExSockaddrs function calls. 


dwReceiveDataLength 
[in] Number of bytes in /oOutoputBuffer that will be used for actual receive data at the 
beginning of the buffer. This size should not include the size of the local address of 
the server, nor the remote address of the client; they are appended to the output 
buffer. If dwReceiveDataLength is zero, accepting the connection will not result in a 
receive operation. Instead, AcceptEx completes as soon as a connection arrives, 
without waiting for any data. 


dwLocalAddressLength 
[in] Number of bytes reserved for the local address information. This value must be at 
least 16 bytes more than the maximum address length for the transport protocol in 
use. 


dwRemoteAddressLength | 
[in] Number of bytes reserved for the remote address information. This value must be 
at least 16 bytes more than the maximum address length for the transport protocol 
in use. 
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lodwBytesReceived 
[out] Pointer to a DWORD that receives the count of bytes received. This parameter is 
set only if the operation completes synchronously. If it returns ERROR_IO_PENDING 
and is completed later, then this DWORD is never set and you must obtain the 
number of bytes read from the completion notification mechanism. 

lpOverlapped | 
[in] An OVERLAPPED structure that is used to process the request. This parameter 
must be specified; it cannot be null. 


Return Values 
If no error occurs, the AcceptEx function completed successfully and a value of TRUE is 
returned. 


If the function fails, AcceptEx returns FALSE. The WSAGetLastError function can then 
be called to return extended error information. If WSAGetLastError returns 
ERROR_IO_PENDING, then the operation was successfully initiated and is still in 
progress. 


Remarks 
The AcceptEx function combines several socket functions into a single API/kernel 
transition. The AcceptEx function, when successful, performs three tasks: 


e Anew connection is accepted. 
e Both the local and remote addresses for the connection are returned. 
—e@ The first block of data sent by the remote is received. 


A program can make a connection to a socket more quickly using AcceptEx instead of 
the accept function. | 


_ A single output buffer receives the data: the local socket address (the server), and the 
remote socket address (the client). 


Using a single buffer improves performance, but the GetAcceptExSockaddrs function 
must be called to parse the buffer into its three distinct parts. 


The buffer size for the local and remote address must be 16 bytes more than the size of 
the SOCKADDR structure for the transport protocol in use because the addresses are 
written in an internal format. For example, the size of a SOCKADDR_IN (the address 
structure for TCP/IP)is 16 bytes. Therefore, a buffer size of at leas 32 bytes must be 
specified for the local and remote addresses. 


The AcceptEx function uses overlapped I/O, unlike the Windows Sockets 11 accept 

function. If your application uses AcceptEx, it can service a large number of clients with 
-arelatively small number of threads. As with all overlapped Win32 functions, either 

_ Win32 events or completion ports can be used as a completion notification mechanism. 
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Another key difference between the AcceptEx function and the Windows Sockets 1.1 
accept function is that the AcceptEx function requires the caller to already have two 
sockets: 


e One that specifies the socket on which to listen. 
e One that specifies the socket on which to accept the connection. 


The sAcceptSocket parameter must be an open socket that is neither bound nor 
connected. 


The /oNumberOfBytes Transferred parameter of the GetQueuedCompletionStatus 
function or the GetOverlappedResult function indicates the number of bytes received in 
the request. 


When this operation is successfully completed, sAcceptHandle can be passed, but to the 
following functions only: 


ReadFile 
WriteFile 
send 

recv 
TransmitFile 
closesocket 


Note If you have called the TransmitFile function with both the TF_DISCONNECT and 
TF_REUSE_SOCKET flags, the specified socket has been returned to a state in which it 
is neither bound nor connected. You can then pass the handle of the socket to the 
AcceptEx function in the sAcceptSocket parameter. 


When the AcceptEx function returns, the socket sAcceptSocket is in the default state for 
a connected socket. The socket sAcceptSocket does not inherit the properties of the 
socket associated with sListenSocket parameter until 
SO_UPDATE_ACCEPT_CONTEXT is set on the socket. Use the setsockopt function to 
set the SO_UPDATE_ACCEPT_CONTEXT option, specifying sAcceptSocket as the 
socket handle and sListenSocket as the option value. 


For example: 


Use the getsockopt function with the SO_CONNECT_TIME option to check whether a 
connection has been accepted. If it has been accepted, you can determine how long the 
connection has been established. The return value is the number of seconds that the 
socket has been connected. If the socket is not connected, the getsockopt returns 
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OxFFFFFFFF. Checking a connection like th 


have been established for a while 


For example 
Notes for ATM 


for important ATM connect 


tup 


lion se 


lion 


documentat 


Windows Sockets 2 accept function 


information. 


Version 


ion 


tens 


IC €X 


A Microsoft-specif 


indows Sockets 1.1 or later. 


ires W 


Requ 


< 
we 
© 
oO 
Yo .- 
re. 
AS 
29 
£3 
O » 
ee) 
C= 
O @Dd 
ow 
QA . 
ge 
© | 
o a 
=e cad 


The Windows Sockets bind function associates a local address with a socket. 


Parameters 


S 


ing an unbound socket 


ify 


iptor ident 


in] Descr 


name 


[in] Address to assign to the socket from the SOCKADDR structure. 


namelen 


ter. 


me parame 


[in] Length of the value in the na 
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Return Values | 


If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, anda 
specific error code can be retrieved by calling WSAGetLastError. 


Remarks 


The bind function is used on an unconnected socket before subsequent calls to the 
connect or listen functions. It is used to bind to either connection-oriented (stream) or 
connectionless (datagram) sockets. When a socket is created with a call to the socket 
function, it exists in a name space (address family), but it has no name assigned to it. 
Use the bind function to establish the local association of the socket by assigning a local 
name to an unnamed socket. 


A name consists of three parts when using the Internet address family: 


e The address family. 
e A host address. 
e A port number that identifies the application. 


In Windows Sockets 2, the name parameter is not strictly interpreted as a pointer to a 
SOCKADDR structure. It is cast this way for Windows Sockets 1.1 compatibility. Service 
providers are free to regard it as a pointer to a block of memory of size namelen. The 
first 2 bytes in this block (corresponding to the sa_family member of the SOCKADDR 
structure) must contain the address family that was used to create the socket. 

Otherwise, an error WSAEFAULT occurs. 


If an application does not care what local address is assigned, specify the manifest 
constant value ADDR_ANY for the sa_data member of the name parameter. This allows 
the underlying service provider to use any appropriate network address, potentially 
simplifying application programming in the presence of multihomed hosts (that is, hosts 
that have more than one network interface and address). 


For TCP/IP, if the port is specified as zero, the service provider assigns a unique port to 
the application with a value between 1024 and 5000. The application can use. 
getsockname after calling bind to learn the address and the port that has been 
assigned to it. If the Internet address is equal to INADDR_ANY, getsockname cannot 


~ necessarily supply the address until the socket is connected, since several addresses 


can be valid if the host is multihomed. Binding to a specific port number other than port O 
is discouraged for client applications, since there is a danger of conflicting with another 
socket already using that port number. 


Notes for IrDA Sockets 

e The Af_irda.h header file must be explicitly included. 

e Local names are not exposed in IrDA. IrDA client sockets therefore, must never call 
the bind function before the connect function. If the IrDA socket was previously 


bound to a service name using bind, the connect function will fail with 
SOCKET_ERROR. 
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e lf the service name is of the form “LSAP-SELxxx”, where xxx is a decimal integer in 
the range 1-127, the address indicates a specific LSAP-SEL xxx rather than a service 
name. Service names such as these allow server applications to accept incoming 
connections directed to a specific LSAP-SEL, without first performing an ISA service 
name query to get the associated LSAP-SEL. One example of this service name type 
is a non-Windows device that does not support IAS. 


Error Codes 
Error code 


WSANOTINITIALISED 


WSAENETDOWN 
WSAEACCES 
WSAEADDRINUSE 


-WSAEADDRNOTAVAIL 
WSAEFAULT 


WSAEINPROGRESS 


WSAEINVAL 
WSAENOBUFS 
WSAENOTSOCK 


Meaning | 


A successful WSAStartup call must occur before using this 
function. 


The network subsystem has failed. 


A process on the machine is already bound to the same fully- 
qualified address and the socket has not been marked to allow 
address reuse with SO_REUSEADDR. For example, the IP 
address and port are bound in the af_inet case). (See the 
SO_REUSEADDR socket option under setsockopt.) 


The specified address is not a valid address for this machine. 


The name or namelen parameter is not a valid part of the user 
address space, the namelen parameter is too small, the name 
parameter contains an incorrect address format for the associated 
address family, or the first two bytes of the memory block specified 
by name does not match the address family associated with the 
socket descriptor s. 


A blocking Windows Sockets 1.1 call is in progress, or the service 
provider is still processing a callback function. 


The socket is already bound to an address. 
Not enough buffers available, too many connections. 
_ The descriptor is not a socket. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, connect, 


getsockname, listen, setsockopt, socket, WSACancelBlockingCall 
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closesocket 


The Windows Sockets closesocket function closes an existing socket. 


Parameters 


Ss 
[in] Descriptor identifying the socket to close. 


Return Values 


If no error occurs, closesocket returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Remarks 

The closesocket function closes a socket. Use it to release the socket descriptor s so 
that further references to s fail with the error WSAENOTSOCK. If this is the last 
reference to an underlying socket, the associated naming information and queued data 
are discarded. Any pending blocking, asynchronous calls issued by any thread in this 
process are canceled without posting any notification messages. 


Any pending overlapped send and receive operations 
(WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued 
by any thread in this process are also canceled. Any event, completion routine, or 
completion port action specified for these overlapped operations is performed. The 
pending overlapped operations fail with the error status WSA_OPERATION_ABORTED. 


An application should always have a matching call to closesocket for each successful 
call to socket to return any socket resources to the system. 


The semantics of closesocket are affected by the socket options SO_LINGER and 
SO_DONTLINGER as follows (SO_DONTLINGER is enabled by default; SO_LINGER is 


disabled). 

Option — | Interval Type ofclose —_— Wait for close? 
SO_DONTLINGER | Do not care Graceful ~No 
SO_LINGER Zero Hard No 
SO_LINGER | Nonzero Graceful | Yes 


lf SO_LINGER is set with a zero time-out interval (that is, the LINGER structure 
-members |_onoff is not zero and I_linger is zero), closesocket is not blocked even if 
queued data has not yet been sent or acknowledged. This is called a hard or abortive 
close, because the socket’s virtual circuit is reset immediately, and any unsent data is 
lost. Any recv call on the remote side of the circuit will fail with WSAECONNRESET. 
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lf SO_LINGER is set with a nonzero time-out interval on a blocking socket, the 
closesocket call blocks on a blocking socket until the remaining data has been sent or 
until the time-out expires. This is called a graceful disconnect. If the time-out expires 
before all data has been sent, the Windows Sockets implementation terminates the 
connection before closesocket returns. 


Enabling SO_LINGER with a nonzero time-out interval on a Aenbiosklie socket is not 
recommended. In this case, the call to closesocket will fail with an error of 
WSAEWOULDBLOCK if the close operation cannot be completed immediately. If 
closesocket fails with WSAEWOULDBLOCK the socket handle is still valid, and a 
disconnect is not initiated. The application must call closesocket again to close the 
socket. If SO_DONTLINGER is set on a stream socket by setting the |_onoff member of 
the LINGER structure to zero, the closesocket call will return immediately and does not 
receive WSAWOULDBLOCK whether the socket is blocking or nonblocking. However, 
any data queued for transmission will be sent, if possible, before the underlying socket is 
closed. This is also called a graceful disconnect. In this case, the Windows Sockets 
provider cannot release the socket and other resources for an arbitrary period, thus 
affecting applications that expect to use all available sockets. This is the default behavior 
(SO_DONTLINGER is set by default). 


Note To ensure that all data is sent and received on a connection, an application 
should call shutdown before calling closesocket (see Graceful shutdown, linger 
options, and socket closure for more information). Also note, an FD_CLOSE network 
event is not posted after closesocket is called. 


Here is a summary of closesocket behavior: 
e |lfSO_ DONTLINGER i is enabled (the default setting) it always returns immediately— | 
connection is gracefully closed in the background. 


e IfSO_ LINGER is enabled with a zero time-out: it always returns tates 
connection is reset/terminated. 


e If SO_LINGER is enabled with a nonzero time-out: 
eo with a blocking socket, it blocks until all data sent or time-out expires. 
e witha a nonblocking socket, it returns immediately indicating failure. 


For additional information please see Graceful shutdown, linger options, and socket 
closure for more information. | 


Notes for IrDA sockets 
e The Af_irda. h header file must be explicitly included. 
e For Windows CE, WSAEINTR is not supported. 
_ The standard linger options are supported. 
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Although IrDA does not provide a graceful close, IrDA will defer closing until receive 
queues are purged. Thus, an application can send data and immediately call the 
socket function, and be confident that the receiver will copy the data before receiving 
an FD _CLOSE message. 


Notes for ATM 


The following are important issues s associated with connection isardowh when using 
Asynchronous Transfer Mode (ATM) and Windows Sockets 2: 


Using the closesocket or shutdown functions with SD_SEND or SD_BOTH results 
ina RELEASE signal being sent out on the control channel. Due to ATM’s use of 
separate signal and data channels, it is possible that a RELEASE signal could reach 
the remote end before the last of the data reaches its destination, resulting in a loss of © 
that data. One possible solutions is programming a sufficient delay between the last 
data sent and the closesocket or shutdown function calls for an ATM socket. 


Half Close is not supported by ATM. 
Both abortive and graceful disconnects result ina RELEASE signal being sent out 
with the same cause field. In either case, received data at the remote end of the 


socket is still delivered to the application. See Graceful Shutdown, Linger Options, 
and Socket Closure for more information. 


Error Codes 
Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. 
WSAENETDOWN The network subsystem has failed. 
WSAENOTSOCK The descriptor is not a socket. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or 
: the service provider is still processing a callback function. 

WSAEINTR The (blocking) Windows Socket 1.1 call was canceled 

| through WSACancelBlockingCall. 
WSAEWOULDBLOCK The socket is marked as nonblocking and SO_LINGER is 


set to a nonzero time-out value. 


Version: Requires Windows Sockets 1.1 or later. 


Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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Windows Sockets Programming Considerations Overview, Socket Functions, accept, 
ioctisocket, setsockopt, socket, WSAAsyncSelect, WSADuplicateSocket 


connect 


The Windows Sockets connect function establishes a connection to a specified socket. 


Parameters 
S 


[in] Descriptor identifying an unconnected socket. 


name | 
[in] Name of the socket to which the connection should be established. 


namelen | 
[in] Length of name. 


Return Values 
If no error occurs, connect returns zero. Otherwise, it returns SOCKET_ERROR, and a 
specific error code can be retrieved by calling WSAGetLastError. 


On a blocking socket, the return value indicates success or failure of the connection 
attempt. 


With a nonblocking socket, the connection attempt cannot be completed immediately. In 
this case, connect will return SOCKET_ERROR, and WSAGetLastError will return 
WSAEWOULDBLOCK. In this case, there are three possible scenarios: 


e Use the select function to determine the eUea a of the connection request by 
checking to see if the socket is writeable. 

e |f the application is using WSAAsyncSelect to indicate interest in connection events, 
then the application will receive an FD_CONNECT notification indicating that the 
connect operation is complete (Successfully or not). | 

e If the application is using WSAEventSelect to indicate interest in connection events, 
then the associated event abet will be signaled indicating that the connect operation 
is complete (successfully or not). 
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Until the connection attempt completes on a nonblocking socket, all subsequent calls to 
connect on the same socket will fail with the error code WSAEALREADY, and 
WSAEISCONN when the connection completes successfully. Due to ambiguities in 
version 1.1 of the Windows Sockets specification, error codes returned from connect 
while a connection is already pending may vary among implementations. As a result, it is 
not recommended that applications use multiple calls to connect to detect connection 
completion. If they do, they must be prepared to handle WSAEINVAL and 
WSAEWOULDBLOCK error values the same way that they handle WSAEALREADY, to 
assure robust execution. 


If the error code returned indicates the connection attempt failed (that is, 
WSAECONNREFUSED, WSAENETUNREACH, a aa the application can 
call connect again for the same socket. 


Remarks 


The connect function is used to create a connection to the specified destination. If 
socket s, is unbound, unique values are assigned to the local association by the system, 
and the socket is marked as bound. 


For connection-oriented sockets (for example, type SOCK_STREAM), an active 
connection is initiated to the foreign host using name (an address in the name space of 
the socket; for a detailed description, see bind and SOCKADDR). 


When the socket call completes successfully, the socket is ready to send and receive 
data. If the address member of the structure specified by the name parameter is all 
zeroes, connect will return the error WSAEADDRNOTAVAIL. Any attempt to reconnect 
an active connection will fail with the error code WSAEISCONN. 


For connection-oriented, nonblocking sockets, it is often not possible to complete the 
connection immediately. In such a case, this function returns the error 
WSAEWOULDBLOCK. However, the operation proceeds. 


When the success or failure outcome becomes known, it may be reported in one of two 
ways, depending on how the client registers for notification. 


e Ifthe client uses the select function, success is reported in the writefds set and failure 
is reported in the exceptfds set. 
e If the client uses the functions WSAAsyncSelect or WSAEventSelect, the 
notification is announced with FD_CONNECT and the error code associated with the 
. FD_CONNECT indicates either success or a specific reason for failure. 
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For a connectionless socket (for example, tyoe SOCK_DGRAM), the operation 
performed by connect is merely to establish a default destination address that can be 
used on subsequent send/WSASend and recv/WSARecv calls. Any datagrams 
received from an address other than the destination address specified will be discarded. 
If the address member of the structure specified by name is all zeroes, the socket will be 
disconnected. Then, the default remote address will be indeterminate, so 
send/WSASend and recv/WSARecv calls will return the error code WSAENOTCONN. 
However, sendto/WSASendTo and recvfrom/WSARecvFrom can still be used. The 
default destination can be changed by simply calling connect again, even if the socket is 
already connected. Any datagrams queued for receipt are discarded if name is different 
from the previous connect. 


For connectionless sockets, name can indicate any valid address, including a broadcast 
address. However, to connect to a broadcast address, a socket must use setsockopt to 
enable the SO_BROADCAST option. Otherwise, connect will fail with the error code 
WSAEACCES. 


When a connection between sockets is broken, the sockets should be discarded and 
recreated. When a problem develops on a connected socket, the application must 
discard and recreate the needed sockets in order to return to a stable point. 


Notes for IrDA Sockets 
e The Af_irda.h header file must be explicitly included. 


e |f an existing IrDA connection is detected at the media-access level, 
WSAENETDOWN is returned. _ 


e If active connections to a device with a different address exist, WSAEADDRINUSE | is 
returned. 


e For Windows CE only: lf IAS name resolution fails because another IAS query is in 
progress, WSAEINPROGRESS is returned. In this situation, retrying the operation at 
one-second intervals is recommended. 


e lf the socket is already connected or an éxclusivelmuttipiexed mode e change failed, 
WSAEISCONN is returned. 


e \f the socket was previously bound to a local service name to accept incoming 
connections using bind, WSAEINVAL is returned. Note that once a socket is bound, it 
cannot be used for establishing an outbound connection. 


IrDA implements the connect function with addresses of the form sockaddr_irda. 
Typically, a client application will create a socket with the socket function, scan the 
immediate vicinity for ITTDA devices with the IRLMP_ENUMDEVICES socket option, — 
choose a device from the returned list, form an address, and call connect. There is no 
difference between blocking and nonblocking semantics. 
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Error Codes 
Error code 


WSANOTINITIALISED 


WSAENETDOWN 
WSAEADDRINUSE 


WSAEINTR 
WSAEINPROGRESS 


WSAEALREADY 


WSAEADDRNOTAVAIL 


WSAEAFNOSUPPORT | 


WSAECONNREFUSED 
WSAEFAULT 


WSAEINVAL 
WSAEISCONN 


WSAENETUNREACH 
~ WSAENOBUFS 
WSAENOTSOCK 
WSAETIMEDOUT 
WSAEWOULDBLOCK 


WSAEACCES 


Meaning 


A successful WSAStartup call must occur before using this 
function. 


The network subsystem has failed. 


The socket’s local address is already in use and the socket was not 
marked to allow address reuse with SO_REUSEADDR. This error 
usually occurs when executing bind, but could be delayed until this 
function if the bind was to a partially wildcard address (involving 
ADDR_ANY) and if a specific address needs to be committed at the 
time of this function. 


The blocking Windows Socket 1.1 call was canceled through 
WSACancelBlockingCall. 


A blocking Windows Sockets 1.1 call is in progress, or the service 
provider is still processing a callback function. 


A nonblocking connect call is in progress on the specified socket. 


Note In order to preserve backward compatibility, this error is 
reported as WSAEINVAL to Windows Sockets 1.1 applications that 
link to either Winsock.dll or Wsock32.dll. 


The remote address is not a valid address (such as ADDR_ANY). 
Addresses in the specified family cannot be used with this socket. 
The attempt to connect was forcefully rejected. 


The name or the namelen parameter is not a valid part of the user 
address space, the namelen parameter is too small, or the name 
parameter contains incorrect address format for the associated 
address family. 


The parameter s Is a listening en 

The socket is already connected (connection-oriented sockets 
only). 

The network cannot be reached from this host at this time. 


No buffer space is available. The socket cannot be connected. 

The descriptor is not a socket. 

Attempt to connect timed out without establishing a connection. 
The socket is marked as nonblocking and the connection cannot be 
completed immediately. | | 

Attempt to connect datagram socket to broadcast address failed 
because setsockopt option SO_BROADCAST is not enabled. 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, accept, 
bind, getsockname, select, socket, WSAAsyncSelect, WSAConnect 


EnumProtocols 


Important The EnumProtocols function is a Microsoft-specific extension to the 


Windows Sockets 1.1 specification. This function is obsolete. For the convenience of 
Windows Sockets 1.1 developers, the reference material is included. 


The WSAEnumProtocols function provides equivalent functionality in Windows 
Sockets 2. : 


The EnumProtocols function obtains information about a specified set of network 
protocols that are active on a local host. 


Parameters 


IpiProtocols 


Pointer to a null-terminated array of protocol identifiers. The EnumProtocols function 
obtains information about the protocols specified by this array. _ 


If IpiProtocols is NULL, the function obtains information about all available protocols. 
The following protocol identifier values are defined. 


Value Protocol 
IPPROTO_TCP —_: TCP/IP, a connection/stream-oriented protocol. 
IPPROTO_LUDP) User Datagram Protocol (UDP/IP), a connectionless 


datagram protocol. 
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Value Protocol | | 
ISOPROTO_TP4 10 connection-oriented transport protocol. 
NSPROTO_IPX , IPX. 
NSPROTO_SPX SPX. 
NSPROTO_SPXII SPX IL. 
lpProtocolBuffer 


Pointer to a buffer that the function fills with an array of PROTOCOL_INFO data 
structures. 


IodwBufferLength 
Pointer to a variable that, on input, specifies the size, in bytes, of the buffer pointed to 
by /oProtocolBuffer. 


On output, the function sets this variable to the minimum buffer size needed to 
retrieve all of the requested information. For the function to succeed, the buffer must 
be at least this size. 


Return Values 
If the function succeeds, the return value is the number of PROTOCOL_INFO data 
structures written to the buffer pointed to by /oProtoco/Buffer. 


If the function fails, the return value is SOCKET_ERROR (-1). To get extended error 
information, call GetLastError. GetLastError can return the following extended error 
code. 


Error code | Meaning 
ERROR_INSUFFICIENT_ The buffer pointed to by /pProtoco/Buffer was too small to 
BUFFER | receive all of the relevant PROTOCOL_INFO structures. 


Call the function with a buffer at least as large as the value 
returned in */pdwBufferLength. 


Remarks 


In the following sample code, the EnumProtocols function obtains information about all 
protocols that are available on a system. The code then examines each of the protocols 
in greater detail. 
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GetAddressByName, PROTOCOL_INFO 


GetAcceptExSockaddrs 


The Windows Sockets GetAcceptExSockaddrs function parses the data obtained from 
a call to the AcceptEx function and passes the local and remote addresses to a 
SOCKADDR structure. 


Note This function is a Microsoft-specific extension to the Windows Sockets 
specification. For more information, see Microsoft Extensions and Windows Sockets 2. 


Parameters 
lpOutputBuffer 
[in] Pointer to a buffer that receives the first block of data sent on a connection 


resulting from an AcceptEx call. Must be the same /oOutputBuffer parameter that 
was passed to the AcceptEx function. 


dwReceiveDataLength | | 
[in] Number of bytes in the buffer used for receiving the first data. This value must be 
equal to the CONE aera parameter that was passed to the AcceptEx 
function. 


dwLocalAddressLength 
[in] Number of bytes reserved for the local address information. Must be equal to the 
dwLocalAddressLength parameter that was passed to the ACCEPTS function. 


dwRemoteAddressLength 
[in] Number of bytes reserved for the remote address information. This value must be 
equal to the Of ee Paramore! that was paseo to the PCCOPIER 
function. 
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LocalSockadadr 
[out] Pointer to the SOCKADDR structure that receives the local address of the 
connection (the same information that would be returned by the Windows Sockets 
getsockname function). This parameter must be specified. 
LocalSockaddrLength 
[out] Size of the local address. This parameter must be specified. 
RemoteSockadar _ 
[out] Pointer to the SOCKADDR structure that receives the remote address of the 
connection (the same information that would be returned by the Windows Sockets 
getpeername function). This parameter must be specified. 
RemoteSockaddrLength 
[out] Size of the local address. This parameter must be specified. 


Return Values 
This function does not return a value. 


Remarks 


The GetAcceptExSockaddrs function is used exclusively with the AcceptEx function to 
parse the first data that the socket receives into local and remote addresses. You are 
required to use this function because the AcceptEx function writes address information 
in an internal (TDI) format. The GetAcceptExSockaddrs routine is required to locate the 
SOCKADDR structures in the buffer. | 


Version: Requires Windows Sockets 1.1 or later. A Microsoft-specific extension. 
Header: Declared in Mswsock.h. 
Library: Use Mswsock.lib. 


GetAddressByName 


The GetAddressByName function queries a name space, or a set of default name 
spaces, in order to obtain network address information for a specified network service. 
This process is known as service name resolution. A network service can also use the 
function to obtain local address information that it can use with the bind function. 


Important The GetAddressByName function is a Microsoft-specific extension to the 
Windows Sockets 1.1 specification. This function is obsolete. For the convenience of 
Windows Sockets 1.1 developers, the reference material is as follows. 


The functions detailed in Protocol-Independent Name Resolution provide equivalent 
functionality in Windows Sockets 2. 
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Baas 


Seas 


= 


Parameters see ° | a ee 
dwNameSpace ce er ; aoe 
Specifies the name space, or a set of default name spaces, that the operating system 
will query for network address information. | | 


Use one of the following constants to specify a name space. 
Value Name space 


NS_DEFAULT A set of default name spaces. The function queries each name space 

| within this set. The set of default name spaces typically includes all the 
name spaces installed on the system. System administrators, however, 
can exclude particular name spaces from the set. This is the value that 
most applications should use for dwNameSpace. 


NS_DNS The Domain Name System used in the Internet for host name resolution. 


NS_NETBT The NetBIOS over TCP/IP layer. All Windows NT/Windows 2000 systems 
register their computer names with NetBIOS. This name space is used to 
convert a computer name to an IP address that uses this registration. 
Note that NS_NETBT can access a WINS server to perform the 
resolution. | | ; 


(continued, 
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Value 


NS_SAP 
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(continued) 
Name space 
The Netware Service Advertising Protocol. This can access the Netware 


bindery if appropriate. NS_SAP is a dynamic name space that allows 
registration of services. 


NS_TCPIP_HOSTS Lookup value in the <systemroot>\system32\drivers\etc\hosts file. 
NS_TCPIP_LOCAL Local TCP/IP name resolution mechanisms, including comparisons 


against the local host name and looks up host names am IP addresses in 
cache of host to IP address mappings. 


Most calls to GetAddressByName should use the special value NS_DEFAULT. This 
lets a client get by with no knowledge of which name spaces are available on an 
internetwork. The system administrator determines name space access. Name 
spaces can come and go without the client having to be aware of the changes. 
lpService Type 
Pointer to a globally unique identifier (GUID) that specifies the type of the network 
service. The header file Svcguid.h includes definitions of several GUID service types, 
and macros for worn with them. 
loServiceName 
Pointer to a zero-terminated string that uniquely represents the service name. For 
example, “MY SNA SERVER’. 


Setting joServiceName to NULL is the equivalent of setting dwResolution to 
RES_SERVICE. The function operates in its second mode, obtaining the local 
address to which a service of the specified type should bind. The function stores the 
local address within the LocalAddr member of the CSADDR_INFO structures stored 
into */oCsaddrBuffer. 


lf dwResolution is set to RES_SERVICE, the function ignores the /pServiceName 
parameter. 


lf dwNameSpace is set to NS_DNS, Roe is the name of the host. 
IpiProtocols 

Pointer to a zero-terminated array of protocol identifiers. The function restricts a name 

resolution attempt to name space providers that offer these protocols. This lets the 

caller limit the scope of the search. 

If joiProtocols is NULL, the function obtains information on all available protocols. 
dwResolution — | 


Set of bit flags that specify aspects of the service name resolution process. The 
following bit flags are defined: 


Value 
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Meaning 


RES_SERVICE If set, the function obtains the address to which a service of the 


specified type should bind. This is the equivalent of setting 
IpServiceName to NULL. 


If this flag is clear, normal name resolution occurs. 


RES_FIND_MULTIPLE If this flag is set, the operating system performs an extensive search 


of all name spaces for the service. It asks every appropriate name 
space to resolve the service name. If this flag is clear, the operating 
system stops looking for service addresses as soon as one is found. 


RES_SOFT_SEARCH This flag is valid if the name space supports multiple levels of 


_IpServiceAsyncinfo 


searching. 


If this flag is valid and set, the operating system performs a simple 
and quick search of the name space. This is useful if an application 
only needs to obtain easy-to-find addresses for the service. 


lf this flag is valid and clear, the operating system performs a more 
extensive search of the name space. 


Reserved for future use; must be set to NULL. 


loCsaddrBuffer 


Pointer to a buffer to receive one or more CSADDR_INFO data structures. The 
number of structures written to the buffer depends on the amount of information found 
in the resolution attempt. You should assume that multiple structures will be written, 
although in many cases there will only be one. 


lpdwBufferLength 


Pointer to a variable that, upon input, specifies the size, in bytes, of the buffer pointed 
to by |pCsadadrBuffer. 


Upon output, this variable contains the total number of bytes réquired to store the 


array of CSADDR_INFO structures. If this value is less than or equal to the input 


value of */pdwBufferLength, and the function is successful, this is the number of bytes 
actually stored in the buffer. If this value is greater than the input value of 
*lpdwBufferLength, the buffer was too small, and the output value of 
*lpdwBufferLength is the minimal required buffer size. 


_ |pAliasBuffer 
- Pointer to a buffer to receive alias information for the network service. 


lf aname space supports aliases, the function stores an array of zero-terminated 
name strings into the buffer pointed to by /pAliasBuffer. There is a double zero- 
terminator at the end of the list. The first name in the array is the service’s primary 
name. Names that follow are aliases. An example of a name space that Supports | 


_ aliases is DNS. 


If aname Spaees does not support aliases, it stores a double zero-terminator into the 
buffer. : 
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This parameter is optional, and can be set to NULL. 


lpdwAliasBufferLength 
Pointer to a variable that, upon input, specifies the size, in bytes, of the buffer pointed 
to by /pAliasBuffer. 


Upon output, this variable contains the total number of bytes satired to store the 
array of name strings. If this value is less than or equal to the input value of 
*|pdwAliasBufferLength, and the function is successful, this is the number of bytes 
actually stored in the buffer. If this value is greater than the input value of © 
*|pdwAliasBufferLength, the buffer was too small, and the output value of 
*|pdwAliasBufferLength is the minimal required buffer size. 


If joAliasBuffer is NULL, |odwAliasBufferLength is meaningless and can also be 
NULL. 


Return Values 
If the function succeeds, the return value is the number of CSADDR_ INFO data 
structures written to the buffer pointed to by joCsaddrBuffer. 


If the function fails, the return value is SOCKET _ERROR(-1). To get extended error 
information, call GetLastError. GetLastError can return the following extended error 


value. 

Errorcode Meaning 

ERROR_INSUFFICIENT_ ‘The buffer pointed to by /oCsadadrBuffer was too small to 

BUFFER. receive all of the relevant CSADDR_INFO structures. Call 
the function with a buffer at least as large as the value 
returned in */odwBufferLength. 

Remarks 


This function is a more powerful version of the windows Sockets function 
gethostbyname The GetAddressByName function works with multiple name services. 


The GetAddressByName function lets a client obtain a Windows Sockets address for a 
network service. The client specifies the service of interest by its service type and 
service name. 


Many name services support a default prefix or suffix that the name =e ivicaipiouider 
considers when resolving service names. For example, in the DNS name space, if a 
domain is named “nt.microsoft.com”, and “ftp millikan” is provided as input, the DNS 
software fails to resolve “millikan”, but successfully resolves “millikan.nt.microsoft.com”. 


Note that the GetAddressByName function can search for a service address in two 
ways: within a particular name space, or within a set of default name spaces. Using a 
default name space, an administrator can specify that certain name spaces will be 
searched for service addresses only if specified by name. An administrator or name 
space setup program can also control the ordering of name space searches. 
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Version: Requires Windows Sockets 1.1. A Microsoft-specific extension. Obsolete for 
Windows Sockets 2.0. 

Header: Declared in Nspapi.h. 

Library: Use Wsock32.lib. | 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


gethostbyname, CSADDR_INFO 


gethostbyaddr 


The Windows Sockets gethostbyaddr function retrieves the host information 
corresponding to a network address. 


Parameters 
adar | 
[in] Pointer to an address in network byte order. 
len ., wees | \ 
[in] Length of the address. te erg ha 
[in] Type of the address, such as the AF_INET address family type (defined as TCP, 


UDP, and other associated Internet protocols). Address family types and their 
corresponding values are defined in the winsock2.h header file. 


Return Values 

If no error occurs, gethostbyaddr returns a pointer to the HOSTENT structure. 
Otherwise, it returns a NULL pointer, and a specific error code can be retrieved by 
calling WSAGetLastError. 7 } 


Error code eee Meaning» 

WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. : | 

WSAENETDOWN The network subsystem has failed. 


(continued) 
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(continued) 

Error code Meaning 

WSAHOST_NOT_FOUND Authoritative answer host not found. 

WSATRY_AGAIN Nonauthoritative host not found, or server failed. 

WSANO_RECOVERY A nonrecoverable error occurred. 

WSANO_DATA Valid name, no data record of requested type. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or 
the service provider is still processing a callback function. 

WSAEAFNOSUPPORT The type specified is not supported by the Windows 
Sockets implementation. 

WSAEFAULT The addr parameter is not a valid part of the user 
address space, or the /en parameter is too small. 

WSAEINTR | A blocking Windows Socket 1.1 call was canceled 
through WSACancelBlockingCall. 

Remarks | 


The gethostbyaddr function returns a pointer to the HOSTENT structure that contains 
the name and address corresponding to the given network address. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


gethostbyname, HOSTENT, WSAAsyncGetHostByAddr 


gethostbyname 


- The Windows Sockets gethostbyname function retrieves host information 
corresponding to a host name from a host database. 


Parameters 
name 
[out] Pointer to the null-terminated name of the host to resolve. 
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Return Values 

If no error occurs, gethostbyname | returns a pointer to the HOSTENT structure 
described above. Otherwise, it returns a NULL pointer and a specific error number can 
be retrieved by calling WSAGetLastError. | 


Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before 
| using this function. | 
WSAENETDOWN The network subsystem has failed. 
WSAHOST_NOT_FOUND Authoritative answer host not found. 
WSATRY_AGAIN | Nonauthoritative host not found, or server failure. 
WSANO_RECOVERY | A nonrecoverable error occurred.. | 
WSANO_DATA Valid name, no data record of requested type. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service Aes is still processing a callback 
function. 
WSAEFAULT The name parameter is nota valid part of the user 
| address space. | 
WSAEINTR A blocking Windows Socket 1.1 call was canceled | 


rere? Oneness 


Remarks 

The gethostbyname function returns a pointer to a -HOSTENT structure—a structure 
allocated by Windows Sockets. The HOSTENT structure contains the results of a 
successful search for the host specified in the name parameter. 


The application must never attempt to modify this structure or to free any of its 
components. Furthermore, only one copy of this structure is allocated per thread, so the 
application should copy any information it needs before issuing any other Windows 
sockets function calls. = 


The gethostbyname function cannot resolve IP address strings passed to it. Such a 
request is treated exactly as if an unknown host name were passed. Use inet_addr to 
convert an IP address string the string to an actual IP address, then use another 
function, gethostbyaddr, to obtain the contents of the HOSTENT structure. 


_ The gethostbyname function resolves the string returned by a successful call to. 
getiiosiname.. | | ae 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. | 
_ Library: Use Ws2_32.lib. 
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gethostbyaddr, WSAAsyncGetHostByName 


gethostname 


The Windows Sockets gethostname function returns the standard host name for the 
local machine. 


Parameters 


name | 
[out] Pointer to a buffer that receives the local host name. 


namelen 
[in] Length of the buffer. 


Return Values 


lf no error occurs, gethostname returns zero. Otherwise, it returns SOCKET_ Emon 
and a specific error code can be retrieved by calling WSAGetLastError. 


Error code | Meaning 


WSAEFAULT The name parameter is not a valid part of the user address 
space, or the buffer size specified by namelen parameter 
is too small to hold the complete host name. 


WSANOTINITIALISED _ A successful WSAStartup call must occur before using 
| — this function. 
WSAENETDOWN The network subsystem has failed. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 


service provider is still processing a callback function. 


Remarks 
The gethostname function returns the name of the local host into the buffer specified by 
the name parameter. The host name is returned as a null-terminated string. The form of 


_the host name is dependent on the Windows Sockets provider—it can be a simple host 


name, or it can be a fully qualified domain name. However, it is guaranteed that the 
name returned will be successfully parsed by gethostbyname and 
WSAAsyncGetHostByName. 
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Note If no local host name has been configured, gethostname must succeed and 


return a token host name that gethostbyname or WSAAsyncGetHostByName can 
resolve. | | 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. . 


ssaseansnsaeninsanianaiats 


gethostbyname, WSAAsyncGetHostByName 


GetNameByType 


_ The GetNameByType function obtains the name of a network service. The network 
service is specified by its service type. 


Important The GetNameByType function is a Microsoft-specific extension to the 
Windows Sockets 1.1 specification. This function is obsolete. For the convenience of 
Windows Sockets 1.1 developers, the reference material is as follows. 


The functions detailed in Protocol-Independent Name Resolution provide equivalent 
functionality in Windows Sockets 2. 


Parameters 
IpServiceType | | 
Pointer to a globally unique identifier (GUID) that specifies the type of the network 


service. The header file Svcguid.h includes definitions of several GUID service types, 
and macros for working with them. — | 


IpServiceName 


Pointer to a buffer to receive a zero-terminated string that uniquely represents the 
name of the network service. 7 | | 


164 Volume 1 Winsock and QOS | 


dwNameLength 


Pointer to a variable that, on input, specifies the size of the buffer pointed to by 


IpServiceName. On output, the variable contains the actual size of the service name 
string. 


Return Values | 
If the function succeeds, the return value is not SOCKET_ERROR (-—1). 


If the function fails, the return value is SOCKET_ERROR (1). To get extended error 
information, call GetLastError. 


Version: Requires Windows Sockets 1.1. A Microsoft-specific extension. Obsolete for 
Windows Sockets 2.0. 


Header: Declared in Nspapi.h. 
Library: Use Wsock32.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


i 


GetTypeByName 


getpeername 


The Windows Sockets getpeername function retrieves the name of the peer to which a 
socket is connected. 


Parameters 
S 


in] Descriptor identifying a connected socket. 


name 
out] The structure that receives the name of the peer. 


namelen 
in/out] Pointer to the size of the name structure. 
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Return Values 


If no error occurs, getpeername returns zero. Otherwise, a value of SOCKET_ERROR 
is returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before 
| using this function. 

WSAENETDOWN The network subsystem has failed. __ 

WSAEFAULT The name or the namelen parameter is not a valid 


part of the user address space, or the namelen 
parameter is too small. 


WSAEINPROGRESS A blocking Windows Sockets 1. 1 call is in progress, 
or the service provider is still processing a callback 
| function. | 
WSAENOTCONN _ The socket is not connected. 
WSAENOTSOCK The descriptor is not a socket. 
Remarks 


The getpeername function retrieves the name of the peer connected to the socket s and 
stores it in the aSOCKADDR structure identified by name. The getpeername function 
can be used only on a connected socket. For datagram sockets, only the name of a peer 
specified in a previous connect call will be returned—any name specified by a previous 
sendto call will not be returned by getpeername. 


On call, the namelen argument contains the size of the name buffer, in bytes. On return, 
the namelen parameter contains the actual size in bytes of the name returned. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Wsock32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, bind, 
getsockname, socket 


getprotobyname 


The Windows Sockets getprotobyname function retrieves the protocol information © 
corresponding to a protocol name. 
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Parameters 


name — . 
[in] Pointer to a null-terminated protocol name. 


Return Values 


If no error occurs, getprotobyname returns a pointer to the PROTOENT. Otherwise, it 
returns a NULL pointer and a specific error number can be retrieved by calling 


WSAGetLastError. | | —_ | 
Error code Meaning 
WSANOTINITIALISED - A successful WSAStartup call must occur before 
using this function. 
WSAENETDOWN sy The network subsystem has failed. 
WSAHOST_NOT_FOUND Authoritative answer protocol not found. 
WSATRY_AGAIN A nonauthoritative Protocol not found, or server 
| failure. | 
WSANO_RECOVERY Nonrecoverable errors, the protocols database is not 
accessible. | 
WSANO_DATA | | _ Valid name, no data record of requested type. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
| function. 
WSAEFAULT | The name parameter is not a valid part of the user 
address space. 
WSAEINTR A: blocking Windows Socket 1.1 call was canceled 
— through WSACancelBlockingCall. 
Remarks 


The getprotobyname function returns a pointer to the PROTOENT structure containing 
the name(s) and protocol number that correspond to the protocol specified in the name 
parameter. All strings are null-terminated. The PROTOENT structure is allocated by the 
Windows Sockets library. An application must never attempt to modify this structure or to 
free any of its components. Furthermore, like HOSTENT, only one copy of this structure 
is allocated per thread, so the application should copy any information that it needs 
before issuing any other Windows Sockets function calls. 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


getprotobynumber, WSAAsyncGetProtoByName 


getprotobynumber 


The Windows Sockets getprotobynumber EONS retrieves protocol information - 
corresponding to a protocol number. 


Parameters 
number 
[in] Protocol number, in host byte order. 


Return Values 
If no error occurs, getprotobynumber returns a pointer to the PROTOENT structure. 


Otherwise, it returns a NULL pointer and a specific error number can be retrieved by 
calling WSAGetLastError. 


Error code | > Meaning 
WSANOTINITIALISED | A successful WSAStartup call must occur before 
oa using this function. 
WSAENETDOWN The network subsystem has failed. 
WSAHOST_NOT_FOUND Authoritative answer protocol not found. 
WSATRY_AGAIN _ <6 A nonauthoritative nl oleee not found, or server 
_.. ~ failure. 
WSANO_RECOVERY Nonrecoverable errors, the protocols database | is not 
: | accessible. : 
| WSANO_DATA Valid name, no data record of requested type. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
| | | ie —* - or the service provider i is still processing a callback 
| ~ function. } 3 
WSAEINTR | : - Ablocking Windows Socket 1.1 call was canceled 


through WSACancelBlockingCall. 
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Remarks 


This getprotobynumber function returns a pointer to the PROTOENT structure as 
previously described in getprotobyname. The contents of the structure correspond to 


the given protocol number. 


The pointer that is returned points to the structure allocated by Windows Sockets. The 
application must never attempt to modify this structure or to free any of its components. 
Furthermore, only one copy of this structure is allocated per thread, so the application 
should copy any information that it needs before issuing any other Windows Sockets 


function calls. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


getprotobyname, WSAAsyncGetProtoByNumber 


getservbyname 


The Windows Sockets getservbyname function retrieves service information 
corresponding to a service name and protocol. 


Parameters 


name 
[in] Pointer to a null-terminated service name. 


proto 
[in] Optional pointer to a null-terminated protocol name. If this pointer is NULL, 


getservbyname returns the first service entry where name matches the s_name 
member of the SERVENT structure or the s_aliases member of the SERVENT 
structure. Otherwise, getservbyname matches both the name and the proto. 


Return Values | 
If no error occurs, getservbyname returns a pointer to the SERVENT structure. 
| Otherwise, it returns a NULL pointer and a specific error number can be retrieved by 
calling WSAGetLastError. — | | | 
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Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 
WSAENETDOWN The network subsystem has failed. 
WSAHOST_NOT_FOUND Authoritative Answer Service not found. 
WSATRY_AGAIN A nonauthoritative Service not found, or server 
failure. 
WSANO_RECOVERY | Nonrecoverable errors, the services database is not 
| accessible. 
WSANO_DATA Valid name, no data record of requested type. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
| or the service provider is still processing a callback 
7 function. | 
WSAEINTR A blocking Windows Socket 1.1 call was canceled 


through WSACancelBlockingCall. 


Remarks 


The getservbyname function returns a pointer to the SERVENT structure containing the 
name(s) and service number that match the string in the name parameter. All strings are 
null-terminated. 


The pointer that is returned points to the SERVENT structure allocated by the Windows 
Sockets library. The application must never attempt to modify this structure or to free any 
of its components. Furthermore, only one copy of this structure is allocated per thread, 
so the application should copy any information it needs before issuing any other 
Windows Sockets function calls. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


SefseryPyPOr: WSAAsyncGetServByName | 


__getservbyport 


The Windows Sockets getservbyport function retrieves service information 
_. corresponding to a port and protocol. 
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arameters 


port 
[in] Port for a service, in network byte order. 


proto 
[in] Optional pointer to a protocol name. If this is NULL, getservbyport returns the 
first service entry for which the port matches the s_port of the SERVENT structure. 
Otherwise, getservbyport matches both the port and the proto parameters. 


Return Values 


If-no error occurs, getservbyport returns a pointer to the SERVENT structure. 
Otherwise, it returns a NULL pointer and a specific error number can be retrieved by 
calling WSAGetLastError. 


Error code Meaning 
~ WSANOTINITIALISED A successful WSAStartup call must occur before 

using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAHOST_NOT_FOUND Authoritative Answer Service not found. 

WSATRY_AGAIN A nonauthoritative Service not found, or server 
failure. 

WSANO_RECOVERY Nonrecoverable errors, the services database is not 
accessible. 

WSANO_DATA Valid name, no data record of requested type. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 

WSAEFAULT The proto parameter is not a valid part of the user 
address space. 

WSAEINTR | A blocking Windows Socket 1.1 call was canceled 


through WSACancelBlockingCall. 


Remarks 


The getservbyport function returns a pointer to a SERVENT structure as it does in the 
getservbyname function. 
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The SERVENT structure is allocated by Windows Sockets. The application must never 
attempt to modify this structure or to free any of its components. Furthermore, only one 
copy of this structure is allocated per thread, so the application should copy any 
information it needs before issuing any other Windows Sockets function calls. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


getservbyname, WSAAsyncGetServByPort 


GetService 


Important The GetService function is a Microsoft-specific extension to the Windows 
Sockets 1.1 specification. This function is obsolete. For the convenience of Windows _ 
sockets 1.1 developers, the reference material is as follows. 


The functions detailed in Protocol-Independent Name Resolution provide equivalent 
functionality in Windows Sockets 2. | | 


The GetService function obtains information about a network service in the context of a 
set of default name spaces or a specified name space. The network service is specified 
by its type and name. The information about the service is obtained as a set of 
NS_SERVICE_INFO data structures. 


Ss 
esa 
Se 
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Parameters | 
dwNameSpace 


Specifies the name space, or a set of default name spaces, that the operating system 
queries for information about the specified network service. 


Use one of the following constants to specify a name space. 


Value 


NS_DEFAULT 


NS_DNS 


NS_NETBT 


NS_SAP 


NS_TCPIP_HOSTS 


NS_TCPIP_LOCAL 


Name space 


A set of default name spaces. The operating system queries 
each name space within this set. The set of default name spaces 
typically includes all the name spaces installed on the system. 
System administrators, however, can exclude particular name 
spaces from the set. NS_DEFAULT is the value that most 
applications should use for dwNameSpace. 


The Domain Name System used in the Internet for host name 
resolution. 


The NetBIOS over TCP/IP layer. All Windows NT/Windows 2000 
systems register their computer names with NetBIOS. This name 
space is used to resolve a computer name into an IP address 
using this registration. Note that NS_NETBT can access a WINS 
server to perform the resolution. | 


The Netware Service Advertising Protocol. This can access the 
Netware bindery if appropriate. NS_SAP is a dynamic name 
space that allows registration of services. 


Looks up host names and IP addresses in the 
<systemroot>\system32\drivers\etc\hosts file. 


Local TCP/IP name resolution mechanisms, including 
comparisons against the local host name and looks up host 
names and IP addresses in cache of host to IP address 
mappings. 


Most calls to GetService should use the special value NS_ DEFAULT. This lets a 
client get by without knowing available name spaces on an internetwork. The system 
administrator determines name space access. Name spaces can come and go 
without the client newing to be aware of the changes. 


— IpGuid 


Pointer to a globally unique identifier (GUID) that specifies the type of the network 
service. The header file Svcguid.h includes GUID service types from many well- 
known services within the DNS and SAP name spaces. 7 


lpServiceName — 


Pointer to a zero-terminated string that tee represents the service name. For 
example, “MY SNA SERVER’. ta, | 
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dwProperties 
Set of bit flags that specify the service information that the function obtains. Each of 
these bit flag constants, other than PROP_ALL, corresponds to a particular member 
of the SERVICE_INFO data structure. If the flag is set, the function puts information 
into the corresponding member of the data structures stored in “/oBuffer. The 
following bit flags are defined. 


Value Name space 


PROP_COMMENT If this flag is set, the function stores data in the 
lpComment member of the data structures stored in 
*loBufter. | 


PROP_LOCALE If this flag is set, the function stores data in the 
IpLocale member of the data structures stored in 
*loBuffer. 


PROP_DISPLAY_HINT If this flag is set, the function stores data in the 
dwDisplayHint member of the data structures stored 
in */oBuffer. | 


PROP_VERSION If this flag is set, the function stores data in the 
dwVersion member of the data structures stored in 
* IpBuffer. 


PROP_START_TIME If this flag is set, the function stores data in the 
| dwTime member of the data structures stored in 
*loBuffer. 


PROP_MACHINE If this flag is set, the function stores data in the 
IpMachineName member of the data structures 
stored in */oBuffer. 


PROP_ADDRESSES If this flag is set, the function stores data in the 
lpServiceAddress member of the data structures 
stored in */oBuffer. | 


PROP_SD If this flag is set, the function stores data in the 
ServiceSpecificinfo member of the data structures 
stored in */oBuffer. : 


PROP_ALL If this flag is set, the function stores data in all of the 
| | members of the data structures stored in Meee 


IpBuffer 
Pointer to a buffer to receive an array of NS_SERVICE_INFO structures and | 
associated service information. Each NS_SERVICE_INFO structure contains service 
information in the context of a particular name space. Note that if dwNameSpace is 
NS_DEFAULT, the function stores more than one structure into the buffer; otherwise, 
just one structure is stored. 
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~ Each NS_SERVICE_INFO structure contains a SERVICE_INFO structure. The 
members of these SERVICE_INFO structures will contain valid data based on the bit 
flags that are set in the dwProperties parameter. If a member's corresponding bit flag 
is not set in dwProperties, the member's value is undefined. 


The function stores the NS_SERVICE_INFO structures in a consecutive array, 
starting at the beginning of the buffer. The pointers in the contained SERVICE_INFO 
structures point to information that is stored in the buffer between the end of the 
'NS_SERVICE_INFO structures and the end of the buffer. 

lodwBufferSize 
Pointer to a variable that, on input, contains the size, in bytes, of the buffer pointed to 
by /oBuffer. On output, this variable contains the number of bytes required to store the 
requested information. If this output value is greater than the input value, the function 
has failed due to insufficient buffer size. 

IpServiceAsyncinfo 
Reserved for future use. Must be set to NULL. 


Return Values | 
If the function succeeds, the return value is the number of NS_SERVICE_INFO 
structures stored in */pBuffer. Zero indicates that no structures were stored. 


If the function fails, the return value is SOCKET_ERROR (-1). To get extended error 
information, call GetLastError. GetLastError can return one of the following extended 
error values. 


Error code | __Meaning 


ERROR_INSUFFICIENT_BUFFER The buffer pointed to by IpBuffer i is too small to receive all 
of the requested information. Call the function with a 
buffer at least as large as the value returned in 
* jpdwButferSize. | 

ERROR_SERVICE_NOT_FOUND The specified service was not found, or the specified 

| 2s ah ~ name space is not in use. The function return value is 
zero in this case. | 


Version: Requires Windows Sockets 1.1. A Microsoft-specific extension. Obsolete for 
Windows Sockets 2.0. 

Header: Declared in Nspapi.h. 

Library: Use Wsock32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


SetService, NS_SERVICE_INFO, SERVICE_INFO 
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getsockname 


The Windows Sockets getsockname function retrieves the local name for a socket. 


Parameters 
= 
[in] Descriptor identifying a socket. 
name 
[out] Receives the address (aame) of the socket. 


namelen | 
[in/out] Size of the name buffer. 


| Return Values 


If no error occurs, getsockname returns zero. Otherwise, a value of SOCKET_ERROR 
is returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code | Meaning at 

WSANOTINITIALISED A successful WSAStartup call must occur before 
| using this API. | 

WSAENETDOWN _ The network subsystem has failed. 

WSAEFAULT | The name or the namelen parameter is not a valid 


part of the user address space, or the namelen 
parameter is too small. 


WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress, 


or the service provider is still processing a callback 

| | , function. | 
WSAENOTSOCK The descriptor is not a socket. aed | 
WSAEINVAL The socket has not been bound to an address with 


bind, or ADDR_ANY is specified in bind but 
connection has not yet occurs. 


| Remarks | 


The getsockname function retrieves the current name for the specified socket descriptor 
in name. It is used on the bound or connected socket specified by the s parameter. The. 
local association is returned. This call is especially useful when a connect call has been 
made without doing a bind first; the getsockname function provides the only way to 
determine the local association that has been set by the system. — 
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On call, the namelen argument contains the size of the name buffer, in bytes. On return, 
the namelen parameter contains the actual size in bytes of the name parameter. 


The getsockname function does not always return information about the host address 
when the socket has been bound to an unspecified address, unless the socket has been 
connected with connect or accept (for example, using ADDR_ANY). A Windows 
Sockets application must not assume that the address will be specified unless the socket 
is connected. The address that will be used for the socket is unknown unless the socket 
is connected when used in a multihomed host. If the socket is using a connectionless 
protocol, the address may not be available until I/O occurs on the socket. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Winsock2.h. 
Library: Use Wsock32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, bind, 
getpeername, socket 


getsockopt 


The Windows Sockets getsockopt function retrieves a socket option. 


Parameters | | 


Ss | 
[in] Descriptor identifying a socket. 
level | . 
[in] Level at which the option is defined; the supported levels include SOL_SOCKET 
and IPPROTO_TCP. See the Windows Sockets 2 Protocol-Specific Annex (a 


separate document included with the Platform SDK) for more information on protocol- 
specific levels. | 


optname | | 
[in] Socket option for which the value is to be retrieved. 
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optval 
[out] Pointer to the buffer in which the value for the requested eption is to be returned. 


optlen — 
[in/out] Pointer to the size of the optval buffer. 


Return Values 
_ If no error occurs, getsockopt returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using 

| this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEFAULT One of the optval or the optien parameters is not a valid 
part of the user address space, or the optlen parameter is 
too small. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 

WSAEINVAL The /evel parameter is unknown or invalid. 

WSAENOPROTOOPT The option is unknown or unsupported by the indicated 
protocol family. 

WSAENOTSOCK The descriptor is not a socket. 

Remarks 


The getsockopt function retrieves the current value for a socket option associated with 
a socket of any type, in any state, and stores the result in optval. Options can exist at 
multiple protocol levels, but they are always present at the uppermost socket level. 
Options affect socket operations, such as the packet routing and OOB data transfer. 


The value associated with the selected option is returned in the buffer optval. The 
integer pointed to by optlen should originally contain the size of this buffer; on return, it — 
will be set to the size of the value returned. For SO_LINGER, this will be the size of a 
LINGER structure. For most other options, it will be the size of an integer. 


The application is responsible for allocating any memory space pointed to directly or 
indirectly by any of the parameters it specified. 


If the option was never set with setsockopt, then getsockopt returns the default value 
for the option. 


The following options are supported for getsockopt. The Type column identifies the type 
of data addressed by optval. 
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level = SOL_ SOCKET 


Value 


SO_ACCEPTCONN 
SO_BROADCAST 


SO CONDITIONAL. 
ACCEPT 


SO_DEBUG 
SO_DONTLINGER 
SO_DONTROUTE 


SO_ERROR 
SO_GROUP_ID 
SO_GROUP_PRIORITY 
SO_KEEPALIVE 


SO_LINGER 
SO_MAX_MSG_SIZE 


SO_OOBINLINE 


SO_PROTOCOL_INFO 
SO_RCVBUF 
SO_REUSEADDR 
SO_SNDBUF 


SO_TYPE 


PVD_CONFIG 


Type 
BOOL 
BOOL 


BOOL 


BOOL 
BOOL 
BOOL 


int 
GROUP 
int 
BOOL 


LINGER structure 
unsigned int 


BOOL 


WSAPROTOCOL_ 


INFO 
int 
BOOL 


int 
int 


Service Provider 
Dependent 


Meaning 


Socket is listening. 

Socket is configured for the transmission of 
broadcast messages. 

Returns current socket state, either from a 
previous Call to setsockopt or the system 
default. 

Debugging is enabled. 

If TRUE, the SO_LINGER option is disabled. 
Routing is disabled. Not supported on ATM 
sockets. 

Retrieves error status and clear. 

Reserved. 

Reserved. 

Keep-alives are being sent. Not supported on 
ATM sockets. | 

Returns the current linger options. 

Maximum size of a message for message- 
oriented socket types (for example, 
SOCK_DGRAM). Has no meaning for stream 
oriented sockets. 

OOB data is being received in the normal data 
stream. (See section Windows Sockets 1.1 
Blocking Routines and EINPROGRESS for a 
discussion of this topic.) 

Description of protocol information for protocol 
that is bound to this socket. 

Buffer size for receives. 

The socket can be bound to an address which 
is already in use. Not applicable for ATM 
sockets. 

Buffer size for sends. 

The type of the socket (for example, 
SOCK_STREAM). | 

An opaque data structure object from the 
service provider associated with socket s. This 
object stores the current configuration 
information of the service provider. The exact 
format of this data structure is service provider 
specific. 


level = |PPROTO_TCP 
Value | Type 


BOOL 


TCP_NODELAY 


level = NSPROTO_IPX 


Meaning 
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Disables the Nagle algorithm for send 


coalescing. 


Note Windows 2000 and Windows NT support all IPX options. Windows 95 and 
Windows 98 support only the following: 


IPX_PTYPE 
IPX_FILTERPTYPE 
IPX_DSTYPE 
IPX_RECVHDR 
IPX_MAXSIZE 
IPX_ADDRESS 


Value 


IPX_PTYPE 
IPX_FILTERPTYPE 


IPX_DSTYPE 


IPX_EXTENDED_ADDRESS 


IPX_RECVHDR 


IPX_MAXSIZE 


IPX_ADDRESS 


IPX_GETNETINFO 


Type 
int 


int 


int 


BOOL 


BOOL 


int 


IPX ADDRESS DATA 
structure 


IPX_NETNUM DATA 
structure 


Meaning 


Obtains the IPX packet type. 


Obtains the receive filter 
packet type 


Obtain the value of the data 
stream field in the SPX header 
on every packet sent. 


Find out whether extended 
addressing is enabled. 


Find out whether the protocol 
header is sent up on all receive 
headers. 

Obtain the maximum data size 
that can be sent. 

Obtain information about a 
specific adapter to which IPX is 
bound. Adapter numbering is 


base zero. The adapternum 
~ member is filled in upon return. _ 


Obtain information about a 
specific IPX network number. If 
not available in the cache, uses 
RIP to obtain information. 

| (continued) — 
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(continued) 

Value | Type 

IPX_GETNETINFO_NORIP | IPX_NETNUM_ DATA 
structure 

IPX_ IPX SPXCONNSTATUS . 

SPXGETCONNECTIONSTATUS DATA structure 

IPX_ADDRESS_ NOTIFY IPX ADDRESS DATA 
structure 

IPX_MAX_ADAPTER_NUM int 

IPX_RERIPNETNUMBER IPX NETNUM_ DATA 
structure 

IPX_IMMEDIATESPXACK BOOL 


Meaning 


Obtain information about a 
specific IPX network number. If 
not available in the cache, will 
not use RIP to obtain 
information, and returns error. 


Obtains information about a 
connected SPX socket. 


Obtains status notification 
when changes occur on an 
adapter to which IPX is bound. 


Obtains maximum number of 
adapters present, numbered as 
base zero. 


Similar to IPX_GETNETINFO, 
but forces IPX to use RIP for 
resolution, even if the network 
information is in the local 
cache. 


Directs SPX connections not to 
delay before sending an ACK. 
Applications without back-and- 
forth traffic should set this to 
TRUE to increase 
performance. 


BSD options not supported for getsockopt are as follows. 


_ Value | Type Meaning 
SO_RCVLOWAT int Receives low watermark. 
SO_RCVTIMEO int Receives time-out. 
SO SNDLOWAT _ int _ Sends low watermark. 
SO_SNDTIMEO — int Sends time-out. 
TCP_MAXSEG | int Receives TCP maximum-segment size. 


Calling getsockopt with an unsupported option will result in an error code of 
WSAENOPROTOOPT being returned from WSAGetLastError. 


SO_DEBUG 


Windows Sockets service providers are encouraged (but not required) to supply 
output debug information if the SO_DEBUG option is set by an application. The 
mechanism for generating the debug information and the form it takes are beyond the 


scope of this document. 
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SO_ERROR 
The SO_ERROR option returns and resets the per socket-based error code, which is 
different from the per thread based—error code that is handled using the 
WSAGetLastError and WSASetLastError function calls. A successful call using the 
socket does not reset the socket based « error code returned by the SO_.ERROR 
option. 


SO_GROUP_ID 
This option is reserved. This option is also exclusive to getsockopt; the value should 
be NULL. 


SO_GROUP_PRIORITY 
This option is reserved. 


SO_KEEPALIVE 
An application can request that a TCPIIP service provider enable the use of keep- 
alive packets on TCP connections by turning on the SO_KEEPALIVE socket option. 
_A Windows Sockets provider need not support the use of keep-alive: if it does, the 

_ precise semantics are implementation-specific but should conform to section 4.2.3.6 
of RFC 1122: Requirements for Internet Hosts—Communication Layers. If a 
connection is dropped as the result of keep-alives the error code WSAENETRESET is 
returned to any calls in progress on the socket, and any subsequent calls will fail with 
WSAENOTCONN. SO_KEEPALIVE is not supported on ATM sockets, and requests — 
to enable the use of keep-alive packets on an ATM socket results in an error being 
returned by the socket. 


- $O_LINGER 

~  SO_LINGER controls the action taken when unsent data is queued ona socket anda 

_ closesocket is performed. See closesocket for a description of the way in which the 
SO_LINGER settings affect the semantics of closesocket. The application gets the 
current behavior by retrieving a LINGER structure (pointed to by the optval 
parameter). a 


SO_MAX_MSG_ SIZE 
This is a get-only socket option that iadicaies the maximum outbound (send) size of a 
message for message-oriented socket types (for example, SOCK_DGRAM) as 
implemented by a particular service provider. It has no meaning for byte stream 
oriented sockets. There is no provigien to find out the maximum inbound-message 
size 


SO PROTOCOL_INFO | 
This is a get-only option that supplies the WSAPROTOCOL_INFO structure 
associated with this socket. See WSAEnumProtocols for more information about this 
structure. 


SO_SNDBUF | ; 
When a Windows Sockets implementation supports the SO_RCVBUF and 

~ SO_SNDBUF options, an application can request different buffer sizes (larger or 
smaller). The call to setsockopt can succeed even if the implementation did not 
provide the whole amount requested. An application must call this function with the 
same option to check the buffer size actually provided. 


182 


Volume 1 Winsock and QOS 


SO_REUSEADDR 


By default, a socket cannot be bound (see bind) to a local address that is already in 
use. On occasion, however, it can be necessary to reuse an address in this way. 
Because every connection is uniquely identified by the combination of local and 
remote addresses, there is no problem. with having two sockets bound to the same 
local address as long as the remote addresses are different. To inform the Windows 
Sockets provider that a bind on a socket should not be disallowed because the 
desired address is already in use by another socket, the application should set the 
SO_REUSEADDR socket option for the socket before issuing the bind. Note that the 
option is interpreted only at the time of the bind: it is therefore unnecessary (but 
harmless) to set the option on a socket that is not to be bound to an existing address, 
and setting or resetting the option after the bind has no effect on this or any other 
socket. SO_REUSEADDBR is not applicable for ATM sockets, and although requests 
to reuse and address do not result in an error, they have no affect on when an ATM 
socket is in use. 


PVD_CONFIG 


This option retrieves an opaque data structure object from the service provider 
associated with socket s. This object stores the current configuration information of 


_ the service provider. The exact format of this data structure is service provider 


specific. 


TCP_NODELAY 


The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle 
algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The 
Nagle algorithm (described in RFC 896) is very effective in reducing the number of 
small packets sent by a host. The process involves buffering send data when there is 
unacknowledged data already in flight or buffering send data until a full-size packet 
can be sent. It is highly recommended that Windows Sockets implementations enable 
the Nagle Algorithm by default because, for the vast majority of application protocols, 
the Nagle Algorithm can deliver significant performance enhancements. However, for 
some applications this algorithm can impede performance, and setsockopt with the 
same option can be used to turn it off. These are applications where many small 
messages are sent, and the time delays between the messages are maintained. 


Notes for IrDA Sockets 
e The Af_irda.h header file must be explicitly included. 
e Windows CE does not support the WSAENETDOWN return value. 


Windows NT/Windows 2000 will return WSAENETDOWN to indicate the underlying 
transceiver driver failed to initialize with the IrDA protocol stack. 


e IrDA supports several special socket options: 


Value : Type Meaning © 


IRLMP_ENUMDEVICES *DEVICELIST Describes devices in range. 
IRLMP_IAS_ QUERY *IAS_QUERY Retrieve IAS attributes. 
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Before an IrDA socket connection can be initiated, a device address must be obtained 
by performing a getsockopt(,,|RLMP_ENUMDEVICES,,) function call, which returns a 
list of all available IrDA devices. A device address returned from the function call is 
copied into a SOCKADDR_IRDA structure, which in turn is used by a subsequent call to 
the connect function call. 


Discovery can be performed in two ways: 


First, performing a getsockopt function call with the IRLMP_ENUMDEVICES option 
causes a single discovery to be run on each idle adapter. The list of discovered devices 
and cached devices (on active adapters) is returned immediately. The following code 
demonstrates this approach. 


(continued) 
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(continued) 


ee 
ee 
_ 


The second approach to performing discovery of IrDA device addresses is to perform a 
lazy discovery; in this approach, the application is not notified until the discovered 
devices list changes from the last discovery run by the stack. 


The DEVICELIST structure shown in the Type column in the previous table is an 
extendible array of device descriptions. IrDA fills in as many device descriptions as can 
fit in the supplied buffer. The device description consists of a device identifier necessary 
to form a sockaddr_irda structure, and a displayable string describing the device. 


The IAS_QUERY structure shown in the Type column in the previous table is used to 
retrieve a single attribute of a single class from a peer device’s IAS database. The 
application specifies the device and class to query and the attribute and attribute type. 
Note that the device would have been obtained previously by a call to 
getsockopt(IRLMP_ENUMDEVICES). It is expected that the application allocates a 
buffer, of the necessary size, for the returned parameters. 


Many SO level socket options are not meaningful to IrDA; only SO_LINGER and 
SO_DONTLINGER are specifically supported. 


se 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
_ Library: Use Ws2_32.lib. 
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Windows Sockets Programming Considerations Overview, Socket Functions, 
setsockopt, socket, WSAAsyncSelect, WSAConnect, WSAGetLastError, 
WSASetLastError 


GetTypeByName 


Important The GetTypeByName function is a Microsoft-specific extension to the 
Windows Sockets 1.1 specification. This function is obsolete. For the convenience of 
Windows Sockets 1.1 developers, the reference material is as follows. 


The functions detailed in Protocol-Independent Name Resolution provide equivalent 
functionality in Windows Sockets 2. | 


The GetTypeByName function obtains a service type GUID for a network service 
specified by name. 


Parameters 


lpServiceName 
Pointer to a zero-terminated string that uniquely represents the name of the service. 
For example, “MY SNA SERVER’. 
IpServiceType | 
Pointer to a variable to receive a Globally Unique Identifier (GUID) that specifies the 
type of the network service. The header file Svcguid.h includes definitions of several 
GUID service types and macros for working with them. | 


Return Values — 
If the function succeeds, the return value is zero. — 


If the function fails, the return value is SOCKET_ERROR(-1 To get extended error 
information, call GetLastError. GetLastError can return the following extended error 
value. | | 


Volume 1 Winsock and QOS 


186 


Meaning 


Value 


The specified service type is unknown. 


ERROR_SERVICE_DOES_NOT_EXIST 


Obsolete for 


ic extension. 


if 


spec 


A Microsoft- 


{ 


indows Sockets 1. 


W 


Ires 


Requi 


Version 


0 


Windows Sockets 2 


- Declared in Nspapi.h. 


Header 


Implemented as Unicode and ANSI versions on Windows NT/2000. 


Use Wsock32.1 


Library 


Unicode 


g from host to TCP/IP network 


The Windows Sockets htonl function converts a u_lon 


ian) 


-end 


Ig 


is b 


ich 


byte order (wh 


Parameters 
hostlong 


[in] 32-bit number in host byte order. 


Return Values 


s network byte order 


in TCPAP’ 


turns the value 


The htonl function re 


Remarks 


The htonl function takes a 32-bit number in host byte order and returns a 32-bit number 


in the network byte order used in TCP/IP networks. 


Version 
Header 


1 or later 


indows Sockets 1 


inW 


Use Ws2_ 32.lib. 


W 


Ires 


Requ 
Declared 


h 


insock2 


Library 
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Windows Sockets Programming Considerations Overview, Socket Functions, htons, 
ntohi, ntohs, WSAHtonI, WSAHtons, WSANtohI, WSANtohs 


htons 


The Windows Sockets htons function converts a u_ short from host to TCP/IP network 
byte order (which is big-endian). 


Parameters 


hostshort 
[in] 16-bit number in host byte order. 


Remarks | 
The htons function takes a 16-bit number in host byte order and returns a 16-bit number 
in network byte order used in TCP/IP networks. 


Return Values | ee 
The htons function returns the value in TCP/IP network byte order. 


Version: Requires Windows Sockets 1.1 or later. © 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, htonl, 
ntohl, ntohs, WSAHtonI, WSAHtons, WSANtohI, WSANtohs 


iInet_addr 


The Windows Sockets inet_addr function converts a string containing an (lpv4) Internet 
Protocol dotted address into a proper address for the IN_ADDR structure. 
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Parameters 
Cp | 
[in] Null-terminated character string representing a number expressed in the Internet 
standard “.” (dotted) notation. 


Return Values 

If no error occurs, inet_addr returns an unsigned long value containing a suitable binary 
representation of the Internet address given. If the string in the cp parameter does not 
contain a legitimate Internet address, for example if a portion of an “a.b.c.d” address 
exceeds 255, then inet_addr returns the value INADDR_NONE. 


Remarks 


The inet_addr function interprets the eaareeiet string specified by the cp parameter. 
This string represents a numeric Internet address expressed in the Internet standard “.” 
notation. The value returned is a number suitable for use as an Internet address. All 
Internet addresses are returned in IP’s network order (bytes ordered from left to right). If 
you pass in “ “ (a space) to the inet_addr function, inet_addr returns zero. 


Internet Addresses 
Values specified using the “.” “notation take one of the following forms: 


a.b.c.d a.b.c ab a 


When four parts are specified, each is interpreted as a byte of data and assigned, from 
left to right, to the 4 bytes of an Internet address. When an Internet address is viewed as 
a 32-bit integer quantity on the Intel architecture, the bytes referred to above appear as 
“d.c.b.a”. That is, the bytes on an Intel processor are ordered from right to left. 


The parts that make up an address in “.” notation can be decimal, octal or hexadecimal 
as specified in the C language. Numbers that start with “Ox” or “OX” imply hexadecimal. 
Numbers that start with “O” imply octal. All other numbers are interpreted as decimal. 


Internet address value Meaning 
“A.3.2.16” : Decimal 
“004.003.002.020” | Octal — 
“Ox4.0x3.0x2.0x10” Hexadecimal 
“4.003.002.0x10” | Mix 


Note The following notations are only used by Berkeley, and nowhere else on the 
Internet. For compatibility with their software, Dey are supported as oes 


When a three-part address is specified, the last part is interpreted as a 16-bit quantity 
and placed in the right-most 2 bytes of the network address. This makes the three-part 
address format convenient for specifying Class B network addresses as “128.net.host”. 
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When a two-part address is specified, the last part is interpreted as a 24-bit quantity and 
placed in the right-most 3 bytes of the network address. This makes the two-part 
address format convenient for specifying Class A network addresses as “net.host’. 


When only one part is given, the value is stored directly in the network address without 
any byte rearrangement. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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inet_ntoa 


The Windows Sockets inet_ ntoa function converts an (lpv4) Internet network address 
into a String in Internet standard dotted format. 


Parameters 
in | 
[in] Structure that represents an Internet host address. 


Return Values. 


If no error occurs, inet_ntoa returns a character pointer to a static buffer containing the 
text address in standard “.” notation. Otherwise, it returns NULL. 


Remarks 

The inet_ntoa function takes an Internet address structure specified by the in parameter 
and returns an ASCII string representing the address in “.” (dot) notation as in “a.b.c.d.”. 
The string returned by inet_ntoa resides in memory that is allocated by Windows 
Sockets. The application should not make any assumptions about the way in which the 
memory is allocated. The data is guaranteed to be valid until the next Windows Sockets 
function call within the same thread—but no longer. Therefore, the data should be 
copied before another Windows Sockets call is made. 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, inet_addr 


ioctisocket 


The Windows Sockets ioctlsocket function controls the I/O mode of a socket. 


Parameters 

Ss 
[in] Descriptor identifying a socket. 

cmd | ; 

[in] Command to perform on the socket s. 


argp 
[in/out] Pointer to a parameter for cmd. 


Return Values 


Upon successful completion, the ioctlsocket returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 


WSAGetLastError. 

Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
| function. | | 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 

| _ service provider is still processing a callback function. 
WSAENOTSOCK The descriptor sis not a socket. | 
WSAEFAULT The argp parameter is not a valid part of the user address 


- space. 
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Remarks 

The ioctlsocket function can be used on any socket in any state. It is used to set or 
retrieve operating parameters associated with the socket, independent of the protocol 
and communications subsystem. Here are the supported commands to use in the cmd 
parameter and their semantics: | 


FIONBIO | 
Use with a nonzero argp parameter to enable the nonblocking mode of socket s. The 
argp parameter is zero if nonblocking is to be disabled. The argp parameter points to 
an unsigned long value. When a socket is created, it operates in blocking mode by 
default (nonblocking mode is disabled). This is consistent with BSD sockets. 


The WSAAsyncSelect and WSAEventSelect functions automatically set a socket to 
nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a 
socket, then any attempt to use ioctlsocket to set the socket back to blocking mode 
will fail with WSAEINVAL. 


To set the socket back to blocking mode, an application must first disable 
WSAAsyncSelect by calling WSAAsyncSelect with the /Event parameter equal to 
zero, or disable WSAEventSelect by calling WSAEventSelect with the 
[NetworkEvents parameter equal to zero. 


FIONREAD 
Use to determine the amount of data pending in the network’s input buffer that can be 
read from socket s. The argp parameter points to an unsigned long value in which 
ioctlsocket stores the result. If s is stream oriented (for example, type | 
SOCK_STREAM), FIONREAD returns the amount of data that can be read in a single 
call to the recv function; this might not be the same as the total amount of data 
queued on the socket. If s is message oriented (for example, type SOCK_DGRAM), 

-FIONREAD returns the size of the first datagram (message) queued on the socket. 


SIOCATMARK 7 

Use to determine whether or not all OOB data has been read. (See section Windows 
Sockets 1.1 Blocking Routines and EINPROGRESS for a discussion on out of band 
(OOB) data.) This applies only to a stream oriented socket (for example, type 
SOCK_STREAM) that has been configured for in-line reception of any OOB data 
(SO_OOBINLINE). If no OOB data is waiting to be read, the operation returns TRUE. 
Otherwise, it returns FALSE, and the next recv or recvfrom performed on the socket 
will retrieve some or all of the data preceding the mark. The application should use 
the SIOCATMARK operation to determine whether any data remains. If there is any 

- normal data preceding the urgent (out of band) data, it will be received in order. (A 
recv or recvfrom will never mix OOB and normal data in the same call.) The argp 

- parameter points to an unsigned long value i in which toctlsocket stores the Boolean 
result. 
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Compatibility 
This ioctlsocket function performs only a subset of functions on a socket when 
compared to the ioctl function found in Berkeley sockets. The ioctlsocket function has 


no command parameter equivalent to the FIOASYNC of ioctl, and SIOCATMARK is the 
only socket-level command that is supported by ioctlsocket. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_ 32. lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, 
getsockopt, setsockopt, socket, WSAAsyncSelect, WSAEventSelect, WSAloctl 


listen | 


\ 


The Windows Sockets listen function places a socket a state where it is listening for an 
incoming connection. 


Parameters 
S | 

[in] Descriptor identifying a bound, unconnected socket. 
backlog 


[in] Maximum length of the queue of pending connections. If set to SOMAXCONN, the 
underlying service provider responsible for socket s will set the backlog to a maximum 
reasonable value. There is no standard provision to obtain the actual backlog value. 


Return Values 


If no error occurs, listen returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code ; | Meaning 


WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 


-WSAENETDOWN The network subsystem has failed. 
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Error code Meaning 


WSAEADDRINUSE The socket’s local address is already in use and the 
socket was not marked to allow address reuse with 
SO_REUSEADDR. This error usually occurs during 
execution of the bind function, but could be delayed 
until this function if the bind was to a partially 
wildcard address (involving ADDR_ANY) and if a 
specific address needs to be committed at the time of 
this function. 


WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 

7 function. 

WSAEINVAL The socket has not been bound with bind. 

WSAEISCONN The socket is already connected. 

WSAEMFILE _ No more socket descriptors are available. 

WSAENOBUFS No buffer space is available. 

WSAENOTSOCK The descriptor is not a socket. 

WSAEOPNOTSUPP | The referenced socket is not of a type that supports 


the listen operation. 


Remarks | 

To accept connections, a socket is first created with the socket function and bound toa 
local address with the bind function, a backlog for incoming connections is specified with 
listen, and then the connections are accepted with the accept function. Sockets that are 
connection oriented, those of type SOCK_STREAM for example, are used with listen. 
The socket s is put into passive mode where incoming connection requests are | 
acknowledged and queued pending acceptance by the process. 


The listen function is typically used by servers that can have more than one connection 
request at a time. If a connection request arrives and the queue is full, the client will 
receive an error with an indication of WSAECONNREFUSED. | : 


lf there are no available socket descriptors, listen attempts to continue to function. If 
descriptors become available, a later call to listen or accept will refill the queue to the 
current or most recent backlog, if possible, and resume listening for i Incoming .. 
connections. 


An application can call listen more than once on the same socket. This has the effect of 
updating the current backlog for the listening socket. Should there be more pending 

connections than the new backlog value, the excess pending connections will be reset 
and dropped, 
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Notes for IrDA Sockets 
e The Af_irda.h header file must be explicitly included. 
e Windows CE only: The backlog parameter is currently limited (silently) to 2. As in 


4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest valid 
value. 


Compatibility 

The backlog parameter is limited (silently) to a reasonable value as determined by the 
underlying service provider. Illegal values are replaced by the nearest legal value. There 
is no standard provision to find out the actual backlog value. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming, Considerations Overview, Socket Functions, accept, 
connect, socket 


ntohl 


The Windows Sockets ntohl function converts a u_long from TCP/IP network order to 
host byte order (which is little-endian on Intel processors). 


Parameters 


netlong 
[in] 32-bit number in TCP/IP network byte order. 


Return Values 


The ntohl function always returns a value in host byte order. If the netlong parameter 
was already in host byte order, then no operation is performed. 


Remarks 


The ntohl function takes a 32-bit number in TCP/IP network byte order and returns a 
32-bit number in host byte order. 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. | 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, htonl, 
htons, ntohs, WSAHtonI, WSAHtons, WSANtohI, WSANtohs 


ntohs 


The Windows Sockets ntohs function converts a u_short from TCP/IP network byte 
order to host byte order (which is little-endian on Intel processors). 


Parameters 


netshort | 
[in] 16-bit number in TCP/IP network byte order. 


Return Values 


The ntohs function returns the value in host byte order. If the netshort parameter was 
already in host byte order, then no operation is performed. 


Remarks | , 
The ntohs function takes a 16-bit number in TCP/IP network byte order and returns a 
16-bit number in host byte order. | 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 7 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, htonl, 
htons, ntohl, WSAHtonI, WSAHtons, WSANtoh!I, WSANtohs 


recv 
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The Windows Sockets recv function receives data from a connected socket. 


Parameters 
S 


[in] Descriptor identifying a connected socket. 


buf 


[out] Buffer for the incoming data. 


en 
[in] Length of buf. 


flags 


[in] Flag specifying the way in which the call is made. 


Return Values 


If no error occurs, recv returns the number of bytes received. If the connection has been 
gracefully closed, the return value is zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning | 

WSANOTINITIALISED A successful WSAStartup call must occur before usin 
this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEFAULT The buf parameter is not completely contained in a vali 
part of the user address space. 

WSAENOTCONN The socket is not connected. 

WSAEINTR | The (blocking) call was canceled through 


WSAEINPROGRESS 


WSAENETRESET 


WSAENOTSOCK 


WSACancelIBlockingCall. 


blocking Windows Sockets 1.1 call is in progress, or 
the service provider is still processing a callback function. 


The connection has been broken due to the keep-alive 
activity detecting a failure while the operation was in 
progress. | 


The descriptor is not a socket. 


Error code 


WSAEOPNOTSUPP > 


WSAESHUTDOWN 


WSAEWOULDBLOCK 
WSAEMSGSIZE 
WSAEINVAL 


WSAECONNABORTED 


WSAETIMEDOUT 


WSAECONNRESET 


Remarks 
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Meaning 


MSG_OOB was specified, but the socket is not stream- 
style such as type SOCK_STREAM, OOB data is not 
supported in the communication domain associated with 
this socket, or the socket is unidirectional and supports 
only send operations. 


The socket has been shut down; it is not possible to 
receive on a socket after shutdown has been invoked 
with how set to SD_RECEIVE or SD_BOTH. 

The socket is marked as nonblocking and the receive 
operation would block. 

The message was too large to fit into the specified buffer 
and was truncated. 

The socket has not been bound with bind, or an 
unknown flag was specified, or MSG_OOB was specified 
for a socket with SO_OOBINLINE enabled or (for byte 
stream sockets only) /en was zero or negative. | 
The virtual circuit was terminated due to a time-out or 
other failure. The application should close the socket as it 
is no longer usable. | 


The connection has been dropped because of a network 


~ failure or because the peer system failed to respond. 


The virtual circuit was reset by the remote side executing 
a hard or abortive close. The application should close the 
socket as it is no longer usable. On a UPD-datagram 
socket this error would indicate that a previous send 
operation resulted in an ICMP “Port Unreachable” 
message. : 


The recv function is used to read incoming data on connection- oriented sockets, or 
connectionless sockets. When using a connection-oriented protocol, the sockets must be 
connected before calling recv. When using a connectionless Das the sockets must 


be bound before calling recv. 


The local address of the socket must be known. For server eepicaionas use an explicit 
bind function or an implicit accept or WSAAccept function. Explicit binding is 
discouraged for client applications. For client applications, the socket can become bound 
implicitly to a local aacles: using connect, WSAConnect, sendto, WeAsenalo, or 


WSAJoinLeaf. 
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For connected or connectionless sockets, the recv function restricts the addresses from 
which received messages are accepted. The function only returns messages from the 
remote address specified in the connection. meoeagee from other addresses are 
(silently) discarded. 


For connection-oriented sockets (type SOCK_ STREAM for example), calling recv will 
return as much information as is currently available—up to the size of the buffer 
supplied. If the socket has been configured for in-line reception of OOB data (socket 
option SO_OOBINLINE) and OOB data is yet unread, only OOB data will be returned. 
The application can use the ioctisocket or WSAloctl SIOCATMARK command to 
determine whether any more OOB data remains to be read. 


For connectionless sockets (tyoe SOCK_DGRAM or other message-oriented sockets), 
data is extracted from the first enqueued datagram (message) from the destination 
address specified by the connect function. 


If the datagram or message is larger than the buffer supplied, the buffer is filled with the 
first part of the datagram, and recv generates the error WSAEMSGSIZE. For unreliable 
protocols (for example, UDP) the excess data is lost; for reliable protocols, the data is 
retained by the service provider until it is amet | read by calling recv with a large 
enough buffer. _ 


If no incoming data is available at the socket, the recv call blocks and waits for data to 
arrive according to the blocking rules defined for WSARecv with the MSG_PARTIAL flag 


not set unless the socket is nonblocking. In this case, a value of SOCKET_ERROR is 


returned with the error code set to WSAEWOULDBLOCK. The select, 
WSAAsyncSelect, or WSAEventSelect functions can be used to determine when more 
data arrives. 


_ If the socket is connection oriented and the remote side has shut down the connection 


gracefully, and all data has been received, a recv will complete immediately with zero 
bytes received. If the connection has been reset, a recv will fail with the error 
WSAECONNRESET. 


The flags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. The semantics of this function 
are determined by the socket options and the flags parameter. The latter is constructed 
by using the bitwise OR operator with any of the following values. 


Value Meaning. 


MSG_PEEK Peeks at the incoming data. The data is copied into the buffer 


but is not removed from the input queue. The function then 
returns the number of bytes currently pending to receive. 


~MSG_OOB Processes OOB data. (See section DECnet Out-of-band data 


for a discussion of this topic.) 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, recvfrom, 
select, send, socket, WSAAsyncsSelect, WSARecvEx 


recvfrom 


The Windows Sockets recvfrom function receives a datagram and stores the source 
address. 


Parameters 

[in] Descriptor identifying a bound socket. 
buf 

[out] Buffer for the incoming data. 
len 

[in] Length of buf. 
flags 

[in] Indicator specifying the way in which the call is made. 
from 

[out] Optional pointes to a buffer that will hold the source address upon return. 
fromlen 


[in/out] Optional pointer to the size of the from buffer. 


Return Values 

If no error occurs, recvfrom returns the number of bytes received. If the connection has 
been gracefully closed, the return value is zero. Otherwise, a value of SOCKET_ERROR 
is returned, and a specific error code can be retrieved by calling WSAGetLastError. 
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Error code 
WSANOTINITIALISED 


WSAENETDOWN 
WSAEFAULT 


WSAEINTR 


~WSAEINPROGRESS 


~WSAEINVAL 


WSAEISCONN 
WSAENETRESET 
WSAENOTSOCK 


WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


WSAETIMEDOUT 


WSAECONNRESET 


Meaning 


A successful WSAStartup call must occur before using 
this function. 


The network subsystem has failed. 


The buf or from parameters are not part of the user 
address space, or the fromlen parameter is too small to 
accommodate the peer address. 


The (blocking) call was canceled through 
WSACancelBlockingCall. 


A blocking Windows Sockets 1.1 call is in progress, or 
the service provider is still processing a callback function. 


The socket has not been bound with bind, or an 
unknown flag was specified, or MSG_OOB was specified 
for a socket with SO_OOBINLINE enabled, or (for byte 
stream-style sockets only) /en was zero or negative. 

The socket is connected. This function is not permitted 
with a connected socket, whether the socket is 
connection-oriented or connectionless. 

The connection has been broken due to the keep-alive 
activity detecting a failure while the operation was in 


- progress. 


The descriptor is not a socket. 


MSG_OOB was specified, but the socket is not stream- 
style such as type SOCK_STREAM, OOB data is not 
supported in the communication domain associated with 
this socket, or the socket is unidirectional and supports 
only send operations. 


The socket has been shut down; it is not possible to 
recvfrom on a socket after shutdown has been invoked 
with how set to SD_RECEIVE or SD_BOTH. 


The socket is marked as nonblocking and the recvfrom 
operation would block. 


The message was too large to fit into the specified buffer 
and was truncated. 


The connection has been dropped, because of a network 
failure or because the system on the other end went 
down without notice. 


The virtual circuit was reset by the remote side executing 
a hard or abortive close. The application should close the 
socket as it is no longer usable. On a UPD-datagram 


socket this error would indicate that a previous send | 


operation resulted in an ICMP “Port Unreachable” 
message. 
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Remarks 


The recvfrom function reads incoming data on both connected and unconnected 
sockets and captures the address from which the data was sent. The socket must not be 
connected. The local address of the socket must be known. For server applications, this 
is usually done explicitly through bind. Explicit binding is discouraged for client 
applications. For client applications using this function, the socket can become bound 
implicitly to a local address through sendto, WSASendTo, or WSAJoinLeaf. 


For stream-oriented sockets such as those of type SOCK_STREAM, a call to recvfrom 
returns as much information as is currently available—up to the size of the buffer 
supplied. If the socket has been configured for inline reception of OOB data (socket 
option SO_OOBINLINE) and OOB data is yet unread, only OOB data will be returned. 
The application can use the ioctlsocket or WSAloctl SIOCATMARK command to 
determine whether any more OOB data remains to be read. The from and fromlen 
parameters are ignored for connection-oriented sockets. 


For message-oriented sockets, data is extracted from the first saatielisd message, up to 
the size of the buffer supplied. If the datagram or message is larger than the buffer 
supplied, the buffer is filled with the first part of the datagram, and recvfrom generates 
the error WSAEMSGSIZE. For unreliable protocols (for sll ie UDP) the excess data 
is lost. 


lf the from parameter is nonzero and the socket is not connection oriented, (type 
SOCK_DGRAM for example), the network address of the peer that sent the data is 
copied to the corresponding SOCKADDR structure. The value pointed to by fromlen is 
initialized to the size of this structure and is modified, on return, to Indicate the actual 


- gize of the address stored in the SOCKADDR structure. 


lf no incoming data is available at the socket, the recvfrom function blocks and waits for 
data to arrive according to the blocking rules defined for WSARecv with the 
MSG_PARTIAL flag not set unless the socket is nonblocking. In this case, a value of 
SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The | 
select, WSAAsyncSelect, or WSAEventSelect can be used to determine when more 
data arrives. | 


If the socket is connection oriented and the remote side has shut down the connection 
gracefully, the call to recvfrom will complete immediately with zero bytes received. If the 
connection has been reset recvfrom will fail with the error WSGAECONNRESET. 


The flags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. The semantics of this function 
are determined by the socket options and the flags parameter. The latter is constructed 
by using the bitwise OR Sd) with any of the following values. 
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Value | Meaning 


MSG_PEEK Peeks at the incoming data. The data is copied into the buffer 
but is not removed from the input queue, and the function 
returns the number of bytes currently pending to receive. 


MSG_OOB Processes OOB data. (See section DECnet Out-Of-band data 
for a discussion of this topic. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, recv, 
send, socket, WSAAsyncSelect, WSAEventSelect 


select 


The Windows Sockets select function determines the status of one or more sockets, 
waiting if necessary, to perform synchronous I/O. 


Parameters 


nfds — 
[in] Ignored. The nfds parameter is included only for compatibility with Berkeley 
sockets. | | 


readfds 
[in/out] Optional pointer to a set of sockets to be checked for readability. 


writefds | | 
[in/out] Optional pointer to a set of sockets to be checked for writability 


exceptfds 
in/out] Optional pointer to a set of sockets to be checked for errors. 
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timeout 
[in] Maximum time for select to wait, provided in the form of a TIMEVAL structure. Set 
the timeout parameter to NULL for blocking operation. 


Return Values 

The select function returns the total number of socket handles that are ready and 
contained in the fd_set structures, zero if the time limit expired, or SOCKET_ERROR if 
an error occurred. If the return value is SOCKET_ERROR, WSAGetLastError can be 
used to retrieve a specific error code. 


Errorcode — Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. 

WSAEFAULT _ The Windows Sockets implementation was unable to 


allocate needed resources for its internal operations, or 
_ the readfds, writefds, exceptfds, or timeval parameters are 
not part of the user address space. 


WSAENETDOWN The network subsystem has failed. 
WSAEINVAL The time-out value is not valid, or all three descriptor 
a parameters were NULL. 
WSAEINTR ~ A blocking Windows Socket 1.1 call was canceled through 
| | WSACancelBlockingCall. 
WSAEINPROGRESS ~ A blocking Windows Sockets 1.1 call is in progress, or the 
| ta as service provider is still processing a callback function. 
WSAENOTSOCK | One of the descriptor sets contains an entry that is not a 
socket. 
Remarks 


The select function is used to determine the status of one or more sockets. For each 
socket, the caller can request information on read, write, or error status. The set of 
sockets for which a given status is requested is indicated by an fd_set structure. The 
sockets contained within the fd_set structures must be associated with a single service 
provider. For the purpose of this restriction, sockets are considered to be from the same 
service provider if the WSAPROTOCOL_INFO structures describing their protocols have 
the same providerld value. Upon return, the structures are updated to reflect the subset — 
of these sockets that meet the specified condition. The select function returns the 
number of sockets meeting the conditions. A set of macros is provided for manipulating 
an fd_set structure. These macros are compatible with those used in the Berkeley 
software, but the underlying representation is completely different. 


The parameter readfds identifies the sockets that are to be checked for eadability.-t If the 
socket is currently in the listen state, it will be marked as readable if an incoming 
connection request has been received such that an accept is guaranteed to complete 
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without blocking. For other sockets, readability means that queued data is available for 
reading such that a call to recv, WSARecv, WSARecvFrom, or recvfrom is guaranteed 
not to block. 


For connection-oriented sockets, readability can also indicate that a request to close the 
socket has been received from the peer. If the virtual circuit was closed gracefully, and 
all data was received, then a recv will return immediately with zero bytes read. If the 
virtual circuit was reset, then a recv will complete immediately with an error code such 
as WSAECONNRESET. The presence of OOB data will be checked if the socket option 
SO_OOBINLINE has been enabled (see setsockopi). 


The parameter writefds identifies the sockets that are to be checked for writability. If a 
socket is processing a connect call (nonblocking), a socket is writeable if the connection 
establishment successfully completes. If the socket is not processing a connect call, 
writability means a send, sendto, or WSASendto are guaranteed to succeed. However, 
they can block on a blocking socket if the /en parameter exceeds the amount of outgoing 
system buffer space available. It is not specified how long these guarantees can be 
assumed to be valid, particularly in a multithreaded environment. 


The parameter exceptfds identifies the sockets that are to be checked for the presence 
of OOB data (see section DECnet Out-of-band data for a discussion of this topic) or any 
exceptional error conditions. 


Important OOB data will only be reported in this way if the option SO_OOBINLINE is 
FALSE. If a socket is processing a connect call (nonblocking), failure of the connect 
attempt is indicated in exceptfds (application must then call getsockopt SO_ERROR to 
determine the error value to describe why the failure occurred). This document does not 
define which other errors will be included. 


Any two of the parameters, readfds, writefds, or exceptids, can be given as NULL. At 
least one must be non-NULL, and any non-NULL descriptor set must contain at least 
one handle to a socket. | 


Summary: A socket will be identified in a 4 particular set when select returns if 
readfds: 


¢ If listen has been called and a connection is pending, accept will succeed. 

e Data is available for reading (includes OOB data if SO_OOBINLINE is enabled). 
e Connection has been closed/reset/terminated. 

writefds: 


e If processing a connect call (nonblocking), connection has succeeded. 
e Data can be sent. 
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excepttds: 


e lf processing a connect call (nonblocking), connection attempt failed. 
e OOB data is available for reading (only if SO_OOBINLINE is disabled). 


Four macros are defined in the header file Winsock2.h for manipulating and checking the 
descriptor sets. The variable FD_SETSIZE determines the maximum number of 
descriptors in a set. (The default value of FD_SETSIZE is 64, which can be modified by 
defining FD_SETSIZE to another value before including Winsock2.h.) Internally, socket 
handles in an fd_set structure are not represented as bit flags as in Berkeley Unix. Their 
data representation is opaque. Use of these macros will maintain software portability 
between different socket environments. The macros to manipulate and check fd_set 
contents are: 


FD_CLR(s, *sei#) 
Removes the descriptor s from set. 
FD_ISSET(s, *se?) | 
Nonzero if s is a member of the set. Otherwise, zero. 
FD_SET(s, *set) 
Adds descriptor s to set. 
FD_ZERO(*se?) 
Initializes the set to the NULL set. 


The parameter time-out controls how long the select can take to complete. If time-out is 
a NULL pointer, select will block indefinitely until at least one descriptor meets the 
specified criteria. Otherwise, time-out points to a TIMEVAL structure that specifies the 

- maximum time that select should wait before returning. When select returns, the 
contents of the TIMEVAL structure are not altered. If TIMEVAL is initialized to {0, 0}, 
select will return immediately; this is used to poll the state of the selected sockets. If 

~ select returns immediately, then the select call is considered nonblocking and the 
standard assumptions for nonblocking calls apply. For example, the blocking hook will 
not be called, and Windows Sockets will not yield. 


Note The select function has no effect on the persistence of socket events registered 
with WSAAsyncSelect or WSAEventSelect. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
_ Library: Use Ws2_32.lib. 
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send ts 


The Windows Sockets send function sends data on a connected socket. 


Parameters 
S 


[in] Descriptor identifying a connected socket. 


buf 
[in] Buffer containing the data to be transmitted. 


en 
[in] Length of the data in buf. 


flags 
| [in] Indicator specifying the way in which the call is made. 


Return Values 


If no error occurs, send returns the total number of bytes sent, which can be less than 
the number indicated by /en for nonblocking sockets. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 


WSAGetLastError. 

Error code — | Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEACCES - The requested address is a broadcast address, but the 


appropriate flag was not set. Call setsockopt with the 
SO_BROADCAST parameter to allow the use of the 
broadcast address. 7 


WSAEINTR __ Ablocking Windows Sockets 1.1 call was canceled 
_ through WSACancelBlockingCall. 


Error code 


WSAEINPROGRESS 
WSAEFAULT 


WSAENETRESET 


WSAENOBUFS 
WSAENOTCONN 
WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


WSAEHOSTUNREACH 


WSAEINVAL 
WSAECONNABORTED 


WSAECONNRESET 


WSAETIMEDOUT 
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Meaning 


A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 
The buf parameter is not completely contained in a valid 
part of the user address space. 

The connection has been broken due to the keep- ive 
activity detecting a failure while the operation was in 
progress. 

No buffer space is available. 

The socket is not connected. 

The descriptor is not a socket. 

MSG_OOB was specified, but the socket is not stream- 
style such as type SOCK_STREAM, OOB data is not 
supported in the communication domain associated with 
this socket, or the socket is unidirectional and supports 
only receive operations. 

The socket has been shut down; it is not possible to send 
on a socket after shutdown has been invoked with how 
set to SD_SEND or SD_BOTH. 


_ The socket is marked as nonblocking and the requested 


operation would block. 


The socket is message oriented, and the message is 
larger than the maximum supported by the underlying 
transport. | 
The remote host cannot be reached from this host at 

this time. 

The socket has not been bound with bind, or an unknown 
flag was specified, or MSG_OOB was specified for a 
socket with SO_OOBINLINE enabled. 

The virtual circuit was terminated due to a time- out or 
other failure. The applications: should close the socket as it © 
is no longer usable. 


The virtual circuit was reset by the remote side executing a 


_ hard or abortive close. For UPD sockets, the remote host 
was unable to deliver a previously sent UDP datagram and 


responded with a “Port Unreachable” ICMP packet. The 
application should close the socket as it is no longer 
usable. 


The connection has péén dropped, because ofa network 


failure or because the system on the other end went down 


without notice. 
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Remarks 


The send function is used to write outgoing data on a connected socket. For message- 
oriented sockets, care must be taken not to exceed the maximum packet size of the 
underlying provider, which can be obtained by using getsockopt to retrieve the value of 
socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through 
the underlying protocol, the error WSAEMSGSIZE is returned, and no data is 
transmitted. 


The successful completion of a send does not indicate that the data was successfully 
delivered. 


If no buffer space is available within the transport system to hold the data to be 
transmitted, send will block unless the socket has been placed in nonblocking mode. On 
nonblocking stream oriented sockets, the number of bytes written can be between 1 and 


the requested length, depending on buffer availability on both client and server 


machines. The select, WSAAsyncSelect or WSAEventSelect functions can be used to - 
determine when it is possible to send more data. 


Calling send with a zero /en parameter is permissible and will be treated by 


~ implementations as successful. In such cases, send will return zero as a valid value. For 


message-oriented sockets, a zero-length transport datagram is sent. 


The flags parameter can be used to influence the behavior of the function beyond the 

options specified for the associated socket. The semantics of this function are | 
determined by the socket options and the flags parameter. The latter is constructed by 
using the bitwise OR operator with any of the following values. 


Value Meaning 


MSG_DONTROUTE Specifies that the data should not be subject to routing. A 
Windows Sockets service provider can choose to ignore this 
flag. 


MSG_OOB Sends OOB data (stream-style socket such as 
_— SOCK_STREAM only. Also see DECnet Out-Of-band data for 
a discussion of this topic). | 


Notes for IrDA Sockets 
The Af_irda.h header file must be explicitly included. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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sendto 


The Windows Sockets sendto function sends data to a specific destination. 


Parameters 
S 


[in] Descriptor identifying a (possibly connected socket. 


buf | | 
_ [in] Buffer containing the data to be transmitted. 


len 
[in] Length of the data in buf. 


flags | | | 
_ [in] Indicator specifying the way in which the call is made. — 
to 

[in] Optional pointer to the address of the target socket. 


tolen 
[in] Size of the address in fo. 


Return Values 


lf no error occurs, sendto returns the total number of bytes sent, which can be less than 
the number indicated by /en. Otherwise, a value of SOCKET_ERROR is returned, and a 
specific error code can be retrieved by calling WSAGetLastError. 


Error code | Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
| oo _ function. 

WSAENETDOWN > The network subsystem has failed. | 


(continued) 
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(continued) 
_ Error code 


WSAEACCES 


WSAEINVAL 
WSAEINTR 
WSAEINPROG RESS 
WSAEFAULT 


WSAENETRESET 


WSAENOBUFS 
WSAENOTCONN 


WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


_ WSAEHOSTUNREACH 


WSAECONNABORTED 


WSAECONNRESET 


Meaning 


The requested address is a broadcast address, but the 


appropriate flag was not set. Call setsockopt with the 
SO_BROADCAST parameter to allow the use of the 
broadcast address. 


An unknown flag was specified, or MSG_OOB was 
specified for a socket with SO_OOBINLINE enabled. 


A blocking Windows Sockets 1.1 call was canceled through 
WSACancelBlockingCall. 


A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 


The buf or to parameters are not part of the user address 
space, or the tolen parameter is too small. 


The connection has been broken due to keep-alive activity 
detecting a failure while the operation was in progress. 


No buffer space is available. 


The socket is not connected (connection-oriented 

sockets only). 

The descriptor is not a socket. 

MSG_OOB was specified, but the socket is not stream-style 
such as type SOCK_STREAM, OOB data is not supported 
in the communication domain associated with this socket, or 
the socket is unidirectional and supports only receive 
Operations. 

The socket has been shut down; it is not possible to sendto 
on a socket after shutdown has been invoked with how set 
to SD_SEND or SD_BOTH. 

The socket is marked as nonblocking and the requested 
operation would block. 

The socket is message oriented, and the message is larger 
than the maximum supported by the underlying transport. 
The remote host cannot be reached from this host at 

this time. Ex | 

The virtual circuit was terminated due to a time-out or other 
failure. The application should close the socket as it is no 
longer usable. 

The virtual circuit was reset by the remote side executing a 


hard or abortive close. For UPD sockets, the remote host 


was unable to deliver a previously sent UDP datagram and 
responded with a “Port Unreachable” ICMP packet. The 
application should close the socket as it is no longer usable. 
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Error code Meaning 

WSAEADDRNOTAVAIL — The remote address is not a valid address, for example, 
ADDR_ANY. 

WSAEAFNOSUPPORT Addresses in the specified family cannot be used with this 
socket. 


WSAEDESTADDRREQ A destination address is required. 
WSAENETUNREACH The network cannot be reached from this host at this time. 


WSAETIMEDOUT The connection has been dropped, because of a network 
failure or because the system on the other end went down 
without notice. | 


Remarks | 

The sendto function is used to write outgoing data on a socket. For message-oriented 
sockets, care must be taken not to exceed the maximum packet size of the underlying 
subnets, which can be obtained by using getsockopt to retrieve the value of socket 
option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the 
underlying protocol, the error WSAEMSGSIZE is returned and no data is transmitted. 


The to parameter can be any valid address in the socket’s address family, including a 
broadcast or any multicast address. To send to a broadcast address, an application must 
have used setsockopt with SO_BROADCAST enabled. Otherwise, sendto will fail with 
the error code WSAEACCES. For TCP/IP, an application can send to any multicast 
address. | | | 


If the socket is unbound, unique values are assigned to the local association by the 
system, and the socket is then marked as bound. An application can use getsockname 
to determine the local socket name in this case. 


The successful completion of a sendto does not indicate that the data was successfully 
delivered. 


The sendto function is normally used on a connectionless socket to send a datagram to 
a specific peer socket identified by the to parameter. Even if the connectionless socket 
has been previously connected to a specific address, the to parameter overrides the 
destination address for that particular datagram only. On a connection-oriented socket, 
the to and to/en parameters are ignored, making sendto equivalent to send. 


- For Sockets Using IP (Version 4) 
To send a broadcast (on a SOCK_DGRAM only), the address in the to parameter should 
be constructed using the special IP address INADDR_BROADCAST (defined in — 
Winsock2.h), together with the intended port number. It is generally inadvisable for a 
broadcast datagram to exceed the size at which fragmentation can occur, which implies 
that the data portion of the datagram (excluding headers) should not exceed 512 bytes. 
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If no buffer space is available within the transport system to hold the data to be 
transmitted, sendto will block unless the socket has been placed in a nonblocking mode. 
On nonblocking, stream oriented sockets, the number of bytes written can be between 1 
and the requested length, depending on buffer availability on both the client and server 
systems. The select, WSAAsyncSelect or WSAEventSelect function can be used to 
determine when it is possible to send more data. | 


Calling sendto with a /en of zero is permissible and will return zero as a valid value. For 
message-oriented sockets, a zero-length transport datagram is sent. 


The flags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. The semantics of this function 
are determined by the socket options and the flags parameter. The latter is constructed 
by using the bitwise OR operator with any of the following values. 


Value Meaning 


MSG_DONTROUTE Specifies that the data should not be subject to routing. A 
Windows Sockets service provider can choose to ignore 
this flag. 

MSG_OOB Sends OOB data (stream-style socket such as 
SOCK_STREAM only. Also see DECnet Out-Of-band data for 
a discussion of this topic.) 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. — 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Functions, recv, 
recvfrom, select, send, socket, WSAAsyncSelect, WSAEventSelect 


SetService 


The SetService function registers or removes from the registry a network service within 
one or more name spaces. The function can also add or remove a network service type 
within one or more name spaces. | 


Important The SetService function is obsolete. For the convenience of Windows 
Sockets 1.1 developers, the reference material is as follows. 


The functions detailed in Protocol-Independent Name Resolution provide equivalent 
functionality in Windows Sockets 2. 
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Parameters 


dwNameSpace 


Name space, or a set of default name spaces, within which the function will operate. 


Use one of the following constants to specify a name space. 
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dwOperation 


Specifies the operation that the function will perform. Use one e the following values 
to epeclly an operation: 


Value 


SERVICE_REGISTER 
SERVICE_DEREGISTER 


SERVICE FLUSH 


SERVICE_ADD_TYPE 


SERVICE_DELETE_TYPE 


dwFlags 


Meaning 


Register the network service with the name space. This operation 
can be used with the SERVICE_FLAG_DEFER and | 
SERVICE_FLAG_HARD bit flags. 


Remove from the registry the network service from the name 
space. This operation can be used with the 
SERVICE_FLAG_DEFER and SERVICE_FLAG_HARD bit flags. 


Perform any operation that was called with the 
SERVICE_FLAG_DEFER bit flag set to one. 


Add a service type to the name space. 


For this operation, use the ServiceSpecificInfo member of the 
SERVICE_INFO structure pointed to by /pServicelnfo to pass a 
SERVICE_TYPE_INFO_ABS structure. You must also set the 
ServiceType member of the SERVICE_INFO structure. Other 
SERVICE_INFO members are ignored. 


Remove a service type, added by a previous call specifying the 
SERVICE_ADD_TYPE operation, from the name space. 


Set of bit flags that pase the function’ S operation. You can set one or more of the 


following bit flags: 
Value 


SERVICE_FLAG_DEFER 


SERVICE_FLAG_HARD 


IpServicelnfo — . 


Name space 


| This bit flag is valid only if the operation is SERVICE_ REGISTER 


or SERVICE_DEREGISTER. 


If this bit flag is one, and it is valid, the name-space provider 
should defer the registration or deregistration operation until a 
SERVICE_FLUSH operation is requested. 


This bit flag is valid only if the operation is SERVICE_REGISTER 
or SERVICE_DEREGISTER. | 


If this bit flag is one, and it is valid, the name-space provider 
updates any relevant persistent store information when me 
operation is performed. 

For example: If the operation involves deregistration in a name 


space that uses a persistent store, the name-space provider would 
remove the relevant persistent store information. 


Pointer to a SERVICE_INFO structure that contains information about the network 
service or service type. 
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IpServiceAsynclnfo 
Reserved for future use. Must be set to NULL. 
lpdwStatusFlags 
Set of bit flags that receive function status information. The following bit flag is 
defined: 
Value Meaning 
SET_SERVICE_ One or more name-space providers were unable to 
PARTIAL_SUCCESS successfully perform the requested operation. 
Return Values 


lf the function fails, the return value is SOCKET_ERROR. To get extended error 
information, call GetLastError. GetLastError can return the following extended error 


value. 

Error code Meaning 

ERROR_ALREADY_ The function tried to register a service that was already 
REGISTERED ~ ‘registered. 


~ Version: Requires Windows Sockets 1.1. Not Pee on Windows 95. Obsolete for 
_ Windows Sockets 2.0. 

Header: Declared in Nspapi.h. 

Library: Use Wsock32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


GetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS 


setsockopt 


The Windows Sockets setsockopt function sets a socket option. 
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Parameters 
S _ 
[in] Descriptor identifying a socket. 
level 
[in] Level at which the option is defined; the supported /evels include SOL_SOCKET 
and IPPROTO_TCP. See the Windows Sockets 2 Protocol-Specific Annex 
(a separate document included with the Platform SDK) for more information on 
protocol-specific levels. 
optname 
[in] Socket option for which the value is to be set. 
optval 
[in] Pointer to the buffer in which the value for the requested option is supplied. 
optlen 
[in] Size of the optval buffer. 


Return Values 


If no error occurs, setsockopt returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning | 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
function. 

WSAENETDOWN The network subsystem has failed. 

WSAEFAULT optval is not in a valid part of the process address $pace or 
optlen parameter is too small. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 

service provider is still processing a callback function. 
WSAEINVAL — | level is not valid, or the information in optval is not valid. 
WSAENETRESET Connection has timed out when SO_KEEPALIVE is set. 


WSAENOPROTOOPT The option is unknown or unsupported for the specified 
provider or socket 


WSAENOTCONN ~ Connection has been reset when SO_KEEPALIVE is set. 


WSAENOTSOCK The descriptor is not a socket. 
Remarks 


The setsockopt function sets the current value for a socket option associated with a 
socket of any type, in any state. Although options can exist at multiple protocol levels, 
they are always present at the uppermost socket level. Options affect socket operations, 
such as whether expedited data (OOB data for example) is received in the normal data 
stream, and whether broadcast messages can be sent on the socket. 
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Note If the setsockopt function is called before the bind function, TCP/IP options will 
not be checked with TCP/IP until the bind occurs. In this case, the setsockopt function 
call will always succeed, but the bind function call may fail because of an early 
setsockopt failing. 


There are two types of socket options: Boolean options that enable or disable a feature 
or behavior, and options that require an integer value or structure. To enable a Boolean 
option, optval points to a nonzero integer. To disable the option optval points to an 
integer equal to zero. The optien parameter should be equal to sizeof(int) for Boolean 
options. For other options, optval points to the an integer or structure that contains the 
desired value for the option, and optlen is the length of the integer or structure. 


The following options are supported for setsockopt. For default values of these options, 
see the description. The Type identifies the type of data addressed by optval. 


level = SOL SOCKET 


Value Type Meaning 
~SO_BROADCAST | BOOL Allows transmission of broadcast messages 
| on the socket. 
SO_CONDITIONAL_ACCEPT BOOL : Enables sockets to delay the | 
| . cy els ie Wa | acknowledgment of a connection until after 
a 2 2 : the WSAAccept condition function is called. 
SO_ DEBUG BOOL | _ Records debugging information. re 
SO_DONTLINGER BOOL Does not block close waiting for unsent data 
to be sent. Setting this option is equivalent to 
setting SO_LINGER with /_ onoff set to zero. 
SO_DONTROUTE ~ BOOL ~ Does not route: sends directly to interface. 
Not supported on ATM sockets (results in an 
error). 
SO_GROUP_PRIORITY int Reserved. | 
SO_KEEPALIVE | BOOL Sends keep-alives. Not supported on ATM 
| sockets (results in an error). 
SO_LINGER structure Lingers on close if unsent data is present. 
LINGER a | 
SO_OOBINLINE BOOL Receives OOB data in the normal data | 
stream. (See section DECnet Out-Of-band _ 
| data for a discussion of this topic.) 
SO_RCVBUF ee int , Specifies the total per-socket buffer space 


reserved for receives. This is unrelated to _ 
SO_MAX._ MSG. SIZE or the size of a TCP 
minnow: 


(continued) 
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(continued) 
Value Type 


SO_REUSEADDR BOOL 


SO_EXCLUSIVEADDRUSE BOOL 


SO SNDBUF | int 

PVD CONFIG Service 
Provider 
Dependent 


level = |PPROTO_TCP' 
Value Type 


TCP_NODELAY BOOL 


Meaning 


Allows the socket to be bound to an address 
that is already in use. (See bind.) Not 
applicable on ATM sockets. 

Enables a socket to be bound for exclusive 
access. Requires Windows NT 4.0 SP4 or 
Windows 2000. 

Specifies the total per-socket buffer space 
reserved for sends. This is unrelated to 


SO MAX_MSG_SIZE or the size of a TCP 


window. 

This object stores the configuration 
information for the service provider 
associated with socket s. The exact format of 
this data structure is service provider specific. 


Meaning 


Disables the Nagle algorithm for send 
coalescing. 


1 Included for backward compatibility with Windows Sockets 1.1. 


level = NSPROTO_IPX 


Note Windows 2000 and Windows NT support all IPX options. Windows 95 and 


Windows 98 support only the following: 


IPX_PTYPE 
IPX_FILTERPTYPE 
IPX_DSTYPE 
IPX_RECVHDR 


IPX_MAXSIZE (used with the getsockopt function) 
_ IPX_ADDRESS (used with the getsockopt function) 


Value Type i 


‘IPX_PTYPE Z int 
IPX_FILTERPTYPE int 
IPX_STOPFILTERPTYPE int 
IPX_DSTYPE int 


Meaning 


Sets the IPX packet type. 
Sets the receive filter packet type 


Stop filtering the filter type set with 
IPX_FILTERTYPE 


Set the value of the data stream field in 
the SPX header on every packet sent. 


Value 


IPX_EXTENDED_ADDRESS 
IPX_RECVHDR 


IPX_RECEIVE_BROADCAST 


IPX_IMMEDIATESPXACK 


BSD options not supported for setsockopt are: 
Type 

~  BOOL 
int 

int 


Value — 


SO_ACCEPTCONN | 
SO_RCVLOWAT 
SO_RCVTIMEO 


SO_SNDLOWAT 
SO_SNDTIMEO | 


- $O_TYPE = 
SO_CONDITIONAL_ACCEPT 


Type 
BOOL 


BOOL 


BOOL 


BOOL 


int 
int 


int 
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Meaning 


Set whether extended addressing is 
enabled. 


Set whether the protocol header is sent 
up on all receive headers. 


Indicates broadcast packets are likely on 
the socket. Set to TRUE by default. 
Applications that do not use broadcasts 
should set this to FALSE for better 
system performance. 


Directs SPX connections not to delay 
before sending an ACK. Applications 
without back-and-forth traffic should set 
this to TRUE to increase performance. 


Meaning 


Socket is listening. 
Receives low watermark. 


Receives time-out (available in Microsoft 
implementation of Windows Sockets 2). 


Sends low watermark. 


Sends time-out (available in Microsoft _ 
implementation of Windows Sockets 2). 


Type of the socket. 


Setting this socket option to TRUE delays the acknowledgment of a connection until 
after the WSAAccept condition function is called. If FALSE, the connection may be 
accepted before the condition function is called, but the connection will be 
disconnected if the condition function rejects the call. This option must be set before 
calling the listen function, otherwise WSAEINVAL is returned. | 
SO_CONDITIONAL_ACCEPT is only supported for TCP and ATM. 

TCP sets SO_CONDITIONAL_ACCEPT to FALSE by default, and therefore by 
default the connection will be accepted before the WSAAccept condition function is 
called. When set to TRUE, the conditional decision must be made within the TCP 
connection timeout. CF_DEFER connections are still subject to the timeout. 

ATM sets SO_CONDITIONAL_ACCEPT to TRUE by default. 
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SO_DEBUG 
Windows Sockets service nrévidere are encouraged (but not required) to supply 
output debug information if the SO_DEBUG option is set by an application. The 
mechanism for generating the debug information and the form it takes are beyond the 
scope of this document. 


SO GROUP_PRIORITY 
Reserved. 


SO _KEEPALIVE 
An application can request that a TCP/IP provider enable the use of keep-alive 
packets on TCP connections by turning on the SO_KEEPALIVE socket option. A 
Windows Sockets provider need not support the use of keep-alives. If it does, the 
precise semantics are implementation-specific but should conform to section 4.2.3.6 
of RFC 1122: Requirements for Internet Hosts—Communication Layers. lf a 
connection is dropped as the result of keep-alives the error code WSAENETRESET is 
returned to any calls in progress on the socket, and any subsequent calls will fail with 
WSAENOTCONN. 


SO_LINGER 
The SO_LINGER option controls the action taken when unsent data is queued on a 
socket and a closesocket is performed. See closesocket for a description of the way 
in which the SO_LINGER settings affect the semantics of closesocket. The 
application sets the desired behavior by creating a LINGER structure (pointed to by 
the opival parameter) with these members I_onoff and |_linger set appropriately. 


SO_REUSEADDR 
By default, a socket cannot be bound (see bind) to a local address that is already in 
use. On occasion, however, it can be necessary to reuse an address in this way. 
Since every connection is uniquely identified by the combination of local and remote 
addresses, there is no problem with having two sockets bound to the same local 
address as long as the remote addresses are different. To inform the Windows 
Sockets provider that a bind on a socket should not be disallowed because the 
desired address is already in use by another socket, the application should set the 
SO_REUSEADDR socket option for the socket before issuing the bind. The option is 
interpreted only at the time of the bind. It is therefore unnecessary and harmless to 
set the option on a socket that is not to be bound to an existing address. Setting or 
resetting the option after the bind has no effect on this or any other socket. 


SO_RCVBUF and SO_SNDBUF : 
When a Windows Sockets implementation supports the SO_RCVBUF and 
SO_SNDBUF options, an application can request different buffer sizes (larger or 
smaller). The call to setsockopt can succeed even when the implementation did not 
provide the whole amount requested. An application must call getsockopt with the 
same option to check the buffer size actually provided. 

PVD_CONFIG | 
This object stores the configuration information for the service provider associated 
with the socket specified in the s parameter. The exact format of this data structure is 
specific to each service provider. 
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TCP_NODELAY 
The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle 
algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The 
process involves buffering send data when there is unacknowledged data already in 
flight or buffering send data until a full-size packet can be sent. It is highly 
recommended that TCP/IP service providers enable the Nagle Algorithm by default, 
and for the vast majority of application protocols the Nagle Algorithm can deliver 
significant performance enhancements. However, for some applications this algorithm 
can impede performance, and TCP_NODELAY can be used to turn it off. These are 
applications where many small messages are sent, and the time delays between the 
messages are maintained. Application writers should not set TCP_NODELAY unless 
the impact of doing so is well-understood and desired because setting 
TCP_NODELAY can have a significant negative impact on network and application 
performance. 


Notes for IrDA Sockets 
e The Af_irda.h header file must be explicitly included. 


e IrDA provides the following settable socket option: 
Value | Type Meaning 


IRLMP_IAS_SET *IAS_SET Sets JAS attributes 


The IRLMP_IAS_SET socket option enables the application to set a single attribute of a 
single class in the local IAS. The application specifies the class to set, the attribute, and 
attribute type. The application is expected to allocate a buffer of the necessary size for 
the passed parameters. 2% 


IrDA provides an IAS database that stores IrDA-based information. Limited access to the 
IAS database is available through the Windows Sockets 2 interface, but such access is 
not normally used by applications, and exists primarily to support connections to non- 
Windows devices that are not compliant with the Windows Sockets 2 IrDA conventions. 


The following structure, IAS_SET, is used with the IRLMP_IAS_SET setsockopt option 
to manage the local IAS database: . 


continued) 
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(continued) 
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Windows Sockets Programming Considerations Overview, Socket Functions, bind, 
getsockopt, ioctlsocket, socket, WSAAsyncSelect, WSAEventSelect 


shutdown 


The Windows Sockets shutdown function disables sends or receives on a socket. 


Parameters 
>: 


how 


[in] Descriptor identifying a socket. 


uy) Flag that describes what types of operation will no onge! be allowed. 


Return Values 


If no error occurs, shutdown returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code 


WSANOTINITIALISED 


WSAENETDOWN 
WSAEINVAL 


WSAEINPROGRESS 


WSAENOTCONN 
WSAENOTSOCK 


Remarks 


Meaning 


A successful WSAStartup call must c occur before 
using this function. 


The network subsystem has failed. 


The how parameter is not valid, or is not consistent 
with the socket type. For example, SD_ SEND i is used 
with a UNI_RECV socket type. _ 


A blocking Windows Sockets 1.1 call is in progress, 


or the service provider | is still processing a callback 


function. 


The socket is not connected (connection: -oriented 
sockets only). | 


The descriptor is not a socket. 


The shutdown function is used on all types of sockets to disable reception, 


transmission, or both. 


224 


Volume 1 Winsock and QOS 


lf the how parameter is SD_RECEIVE, subsequent calls to the recv function on the 
socket will be disallowed. This has no effect on the lower protocol layers. For TCP 
sockets, if there is still data queued on the socket waiting to be received, or data arrives 
subsequently, the connection is reset, since the data cannot be delivered to the user. 
For UDP sockets, incoming datagrams are accepted and queued. In no case will an 
ICMP error packet be generated. 


lf the how parameter is SD_SEND, subsequent calls to the send function are disallowed. 
For TCP sockets, a FIN will be sent after all data is sent and acknowledged by the 
receiver. 


Setting how to SD_BOTH disables both sends and receives as described above. 


The shutdown function does not close the socket. Any resources attached to the socket 
will not be freed until closesocket is invoked. 


To assure that all data is sent and received on a connected socket before it is closed, an 


application should use shutdown to close connection before caning closesocket. For 
example, to initiate a graceful disconnect: 

1. Call WSAAsyncSelect to register for FD_CLOSE notification. 

2. Call shutdown with how=SD_ SEND. 

3. When FD_CLOSE received, call recv until zero returned, or SOCKET_ERROR. 

4. Call closesocket. 


Note The shutdown function does not block regardless of the SO_LINGER setting on 
the socket. 


An application should not rely on being able to reuse a socket after it has been shut 
down. In particular, a Windows Sockets provider is not required to support the use of 
connect on a socket that has been shut down. 


Notes for ATM 


There are important issues associated with connection teardown when using 
Asynchronous Transfer Mode (ATM) and Windows Sockets 2. For more information 
about these important considerations, see the section titled Notes for ATM in the 
Remarks section of the closesocket function reference. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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Windows Sockets Programming Considerations Overview, Socket Fanciioné: connect, 
socket 


socket 


The Windows Sockets socket function creates a socket that is bound to a specific 
service provider. 


Parameters 
af 


[in] Address family specification. 


type 
[in] Type specification for the new socket. 


The following are the only two type specifications supported for Windows Sor nels 1.1: 
Type Explanation 7 


SOCK_STREAM | Provides sequenced, reliable, two-way, connection- based 
| byte streams with an OOB data transmission mechanism. 
Uses TCP for the Internet address family. 


SOCK_DGRAM Supports datagrams, which are connectionless, unreliable 
buffers of a fixed (typically small) maximum length. Uses 
UDP for the Internet address family. 


In Windows Sockets 2, many new socket types will be introduced and no longer need 
to be specified, since an application can dynamically discover the attributes of each 
available transport protocol through the WSAEnumProtocols function. Socket type 
definitions appear in Winsock2.h, which will be periodically updated as new socket 
types, address families, and protocols are defined. 


protocol 
[in] Protocol to be used with the socket that is specific to the indicated address family. 


Return Values | | 

If no error occurs, socket returns a descriptor referencing the new socket. Otherwise, a 
value of INVALID_ SOCKET is returned, anda epeuile error code can be retrieved by 
calling WSAGetLastError. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur 
before using this function. 

WSAENETDOWN The network subsystem or the associated 
service provider has failed. 

WSAEAFNOSUPPORT The specified address family is not supported. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in 


progress, or the service provider is still 
processing a callback function. 


WSAEMFILE | No more socket descriptors are available. 

WSAENOBUFS No buffer space is available. The socket cannot 
be created. 

WSAEPROTONOSUPPORT The specified protocol is not supported. 

WSAEPROTOTYPE The specified protocol is the wrong type for this 
socket. 

WSAESOCKTNOSUPPORT The specified socket type is not supported in this 
address family. 

WSAEBADF For Windows CE AF_IRDA sockets only: the 


shared serial port is busy. 


Remarks 


The socket function causes a socket descriptor and any related resources to be 
allocated and bound to a specific transport-service provider. Windows Sockets will utilize 
the first available service provider that supports the requested combination of address 
family, socket type and protocol parameters. The socket that is created will have the 
overlapped attribute as a default. For Microsoft operating systems, the Microsoft-specific 
socket option, SO_OPENTYPE, defined in Mswsock.h can affect this default. See 
Microsoft-specific documentation for a detailed description of SO_.OPENTYPE. 


Sockets without the overlapped attribute can be created by using WSASocket. All 
functions that allow overlapped operation (WSASend, WSARecv,WSASendTo, 
WSARecvFrom, and WSAloctl) also support nonoverlapped usage on an overlapped 
socket if the values for parameters related to overlapped operation are NULL. 


When selecting a protocol and its supporting service provider this procedure will only 
choose a base protocol or a protocol chain, not a protocol layer by itself. Unchained 
protocol layers are not considered to have partial matches on type or af either. That is, 
they do not lead to an error code of WSAEAFNOSUPPORT or 
WSAEPROTONOSUPPORT if no suitable protocol is found. 
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Important The manifest constant AF_UNSPEC continues to be defined in the header 
file but its use is strongly discouraged, as this can cause ambiguity in interpreting the 
value of the protoco/ parameter. 


Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, 
and must be in a connected state before any data can be sent or received on it. A 
connection to another socket is created with a connect call. Once connected, data can — 
be transferred using send and recv calls. When a session has been completed, a 
closesocket must be performed. 


The communications protocols used to implement a reliable, connection-oriented socket 
ensure that data is not lost or duplicated. If data for which the peer protocol has buffer 
space cannot be successfully transmitted within a reasonable length of time, the 
connection is considered broken and subsequent calls will fail with the error code set to 
WSAETIMEDOUT. 


Connectionless, message-oriented sockets allow sending and receiving of datagrams to 
and from arbitrary peers using sendto and recvfrom. If such a socket is connected to a 
specific peer, datagrams can be sent to that peer using send and can be received only 
from this peer using recv. 


Support for sockets with type RAW is not required, but service providers are encouraged 
_ to support raw sockets as practicable. | 


Notes for IrDA Sockets 
¢ The Af_irda.h header file must be explicitly included. 


e Only SOCK_STREAM is supported; the SOCK_DGRAM type is not supported by 
IrDA. 


e The protocol parameter is always set to 0 for IrDA. 


Note On Windows NT/Windows 2000: raw socket aonb requires administrative 
privileges. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Socket Flinctions, accept, 
bind, connect, getsockname, getsockopt, ioctisocket, listen, recv, ieee our 
select, send, sendto, setsockopt, shutdown, WSASocket oar 
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TransmitFile 


The Windows Sockets TransmitFile function transmits file data over a connected socket 
handle. This function uses the operating system’s cache manager to retrieve the file 
data, and provides high-performance file data transfer over sockets. 


Note This function is a Microsoft-specific extension to the Windows Sockets 
specification. For more information, see Microsoft Extensions and Windows Sockets 2. 


Parameters 


hSocket 
Handle to a connected socket. The TransmitFile function will transmit the file data 


over this socket. The socket specified by hSocket must be a connection-oriented 
socket; the TransmitFile function does not support datagram sockets. Sockets of 


type SOCK_STREAM, SOCK_SEQPACKET, or SOCK_RDM are connection- 
oriented sockets. 


hFile 
Handle to the open file that the TransmitFile function transmits. Since operating 
system reads the file data sequentially, you can improve caching performance by 
opening the handle with FILE_FLAG_SEQUENTIAL_SCAN. The hFile parameter is 
optional; if the hFile parameter is NULL, only data in the header and/or the tail buffer 
is transmitted; any additional action, such as socket disconnect or reuse, is performed 
as specified by the dwFlags parameter. 


nNumberOfBytesTowWrite 
Number of file bytes to transmit. The TransmitFile function completes when it has 
sent the specified number of bytes, or when an error occurs, whichever occurs first. 


Set nNumberOfBytesToWrite to zero in order to transmit the entire file. 


nNumberOfBytesPerSend 
Size of each block of data sent in each send operation, in bytes. This specification is 
used by Windows’ sockets layer. To select the default send size, set 
nNumberOfBytesPerSend to zero. a | 


The nNumberOfBytesPerSend parameter is useful for message protocols that have 
limitations on the size of individual send requests. 
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IpOverlapped 
Pointer to an OVERLAPPED structure. If the socket handle has been opened as 
overlapped, specify this parameter in order to achieve an overlapped (asynchronous) 
I/O operation. By default, socket handles are opened as overlapped. 


You can use /pOverlapped to specify an offset within the file at which to start the file 
data transfer by setting the Offset and OffsetHigh member of the OVERLAPPED 
structure. If /oOverlapped is NULL, the transmission of data always starts at the 
current byte offset in the file. 


When /pOverlapped is not NULL, the overlapped I/O might not finish before 
TransmitFile returns. In that case, the TransmitFile function returns FALSE, and 
GetLastError returns ERROR_IO_PENDING. This enables the caller to continue 
processing while the file transmission operation completes. Windows will set the event 
specified by the hEvent member of the OVERLAPPED structure, or the socket 
specified by hSocket, to the signaled state upon Eompie on of the data transmission 
request. | 


loTransmitBuffers 
Pointer to a TRANSMIT_FILE_BUFFERS data structure that contains pointers to data 
to send before and after the file data is sent. Set the /oTransmitBuffers parameter to 
NULL if you want to transmit only the file data. 


dwFlags 
The dwFlags parameter has six settings: 


TF_DISCONNECT | 
Start a transport-level disconnect after all the file data has been queued for 
transmission. | 


TF_REUSE_SOCKET | 
Prepare the socket handle to be reused. When the TransmitFile request completes, 
the socket handle can be passed to the AcceptEx function. It is only valid if 
TF_DISCONNECT is also specified. 


TF_USE_DEFAULT_WORKER | 
Directs the Windows Sockets service provider to use the system’s default thread to 
process long TransmitFile requests. The system default thread can be adjusted 
using the following registry parameter as a REG_DWORD: 


CurrentControlSet\Services\afd\Parameters\TransmitWorker 


Tes USE _SYSTEM_THREAD 
Directs the Windows Sockets service provider to use system threads to process 
long TransmitFile requests. 


TF_USE_KERNEL_APC 
Directs the driver to use kernel Asynchronous Procedure Calls (APCs) instead of 
worker threads to process long TransmitFile requests. Long TransmitFile requests 
are defined as requests that require more than a single read from the file or a 
cache; the request therefore depends on the size of the file and the specified 
length of the send packet. 
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Use of TF_USE_KERNEL_APC can deliver significant performance benefits. It is 
possible (though unlikely), however, that the thread in which context TransmitFile 
is initiated is being used for heavy computations; this situation may prevent APCs 
from launching. Note that the Windows Sockets kernel mode driver uses normal 
kernel APCs, which launch whenever a thread is in a wait state, which differs from 
user-mode APCs, which launch whenever a thread is in an alertable wait state 
initiated in user mode). 


TF _WRITE_BEHIND 
Complete the TransmitFile request immediately, without pending. If this flag is 
specified and TransmitFile succeeds, then the data has been accepted by the 
system but not necessarily acknowledged by the remote end. Do not use this 
setting with the TF_DISCONNECT and TF_REUSE_SOCKET flags. 


Return Values 


lf the TransmitFile function succeeds, the return value is TRUE. Otherwise, the return 
value is FALSE. To get extended error information, call GetLastError. The function 
returns FALSE if an overlapped I/O operation is not complete before TransmitFile | 
returns. In that case, GetLastError returns ERROR_IO_PENDING. 


Remarks 


The Windows NT Server/Windows 2000 Server spiiniizes the TransmitFile function for 
high performance. The Windows NT Workstation/Windows 2000 Professional optimizes 
the function for minimum memory and resource utilization. Expect better performance 
results when using TransmitFile on Windows NT Server/Windows 2000 Server. 


Note TransmitFile is not functional on transports that perform their own buffering. 
Transports with the TDILSERVICE_INTERNAL_BUFFERING flag set, such as ADSP, 
perform their own buffering. Because TransmitFile achieves its performance gains by 
sending data directly from the file cache. Transports that run out of buffer space on a 
particular connection are not handled by TransmitFile, and as a result of running out of 
buffer space on the connection, TransmitFile returns STATUS_DEVICE_NOT_READY. 


Version: Requires Windows Sockets 1.1 or later. A Microsoft- -specific ¢ extension. Not 
supported on Windows 95. : 

Header: Declared in Mswsock.h. 

Library: Use Mswsock.lib. 


| OVERLAPPED, TRANSMIT_FILE_BUFFERS _ 
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WSAAccept 


The Windows Sockets WSAAccept function conditionally accepts a connection based 
on the return value of a condition function, provides QOS flow specifications, and allows 
the transfer of connection data. 


Parameters 


Ss 
— [in] Descriptor identifying a socket that is listening for connections after a call to the 
listen function. 


addr 
[out] Optional pointer to a buffer that receives the address of the connecting entity, as" 
known to the communications layer. The exact format of the addr parameter is 
determined by the address family established when the socket was created. 


addrlen 
[in/out] Optional pointer to an integer that contains the length of the address addr. 


~ |pfnCondition 

[in] Procedure instance address of the optional, application-supplied condition function 
that will make an accept/reject decision based on the caller information Passed in as 

- parameters. 

dwCallbackData 
[in] Callback data passed back to the application as the value of the dwCallbackData 
parameter of the condition function. This parameter is not interpreted by Windows 
Sockets. 


Return Values 


If no error occurs, WSAAccept returns a value of type SOCKET that is a descriptor for 
the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a 
| specific error code can be retrieved by calling WSAGetLastError. 


The integer referred to by addrlen initially contains the amount of space pdinted to by 
addr. On return it will contain the actual length in bytes of the address returned. 
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Error code 


WSANOTINITIALISED 
WSAECONNREFUSED 
WSAENETDOWN 
WSAEFAULT 
WSAEINTR 
WSAEINPROGRESS 
WSAEINVAL 
WSAEMFILE 


WSAENOBUFS 
WSAENOTSOCK 
WSAEOPNOTSUPP 


WSATRY_AGAIN 


WSAEWOULDBLOCK 


WSAEACCES 


Remarks 


Meaning 


A successful WSAStartup call must occur before using 
this function. 


The connection request was forcefully rejected as 
indicated in the return value of the condition function 
(CF_REJECT). 


The network subsystem has failed. 


The adadrlen parameter is too small or the addr or 
lpfnCondition are not part of the user address space. 


A blocking Windows Sockets 1.1 call was canceled 
through WSACancelBlockingCall. 


A blocking Windows Sockets 1.1 call is in progress. 
listen was not invoked prior to WSAAccept, the return 
value of the condition function is not a valid one, or any 
case where the specified socket is in an invalid state. 
The queue is nonempty upon entry to WSAAccept and 
there are no socket descriptors available. 

No buffer space is available. 

The descriptor is not a socket. 

The referenced socket is not a type that supports 
connection-oriented service. 

The acceptance of the connection request was deferred 
as indicated in the return value of the condition function 
(CF_DEFER). | 

The socket is marked as nonblocking and no connections 
are present to be accepted. 
The connection request that was offered has timed out or 
been withdrawn. 


The WSAAccept function extracts the first connection on the queue of pending 
connections on socket s, and checks it against the condition function, provided the 
condition function is specified (that is, not NULL). If the condition function returns 
CF_ACCEPT, WSAAccept creates a new socket. The newly created socket has the 
same properties as socket s including asynchronous events registered with | 
WSAAsyncSelect or with WSAEventSelect. If the condition function returns 


CF_REJECT, WSAAccept rejects the connection request. The condition function runs in 


the same thread as this function does, and should return as soon as possible. If the 
decision cannot be made immediately, the condition function should return CF_DEFER 
to indicate that no decision has been made, and no action about this connection request 
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should be taken by the service provider. When the application is ready to take action on 
the connection request, it will invoke WSAAccept again and return either CF_ACCEPT 
or CF_REJECT as a return value from the condition function. 


A socket in default mode (blocking) will block until a connection is present when an 
application calls WSAAccept and no connections are pending on the queue. 


A socket in nonblocking mode (blocking) fails with the error WGAEWOULDBLOCK when 
an application calls WSAAccept and no connections are pending on the queue. After 
WSAAccept succeeds and returns a new socket handle, the accepted socket cannot be 
used to accept any more connections. The original socket remains open and listens for 
new connection requests. 


The adar parameter is a result parameter that is filled in with the address of the 
connecting entity, as known to the communications layer. The exact format of the addr 
parameter is determined by the address family in which the communication is occurring. 
The adadrlen is a value-result parameter; it should initially contain the amount of space 
pointed to by addr. On return, it will contain the actual length (in bytes) of the address 
returned. This call is used with connection-oriented socket types such as 
SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about 
the remote address of the accepted socket is returned. Otherwise, these two parameters 
will be filled in regardless of whether the condition function is specified or what it returns. 


A prototype of the condition function is as follows: 


The ConditionFunc is a placeholder for the application-supplied callback function. The | 
actual condition function must reside in a DLL or application module. It is exported in the 
module definition file. Use MakeProcinstance to get a procedure-instance ) aGaress for 
the callback function. 


The /pCallerld parameter points to a WSABUF structure that contains the Addiess of the 
connecting entity, where its /en parameter is the length of the buffer in bytes, and its buf 
parameter is a pointer to the buffer. The /pCallerData is a value parameter that contains 
~ any user data. The information in these parameters is sent along with the connection 
request. If no caller identification or caller data is available, the corresponding — 
parameters will be NULL. Many network protocols do not support connect-time calller 
data. Most conventional network protocols can be expected to support caller identifier 
information at connection-request time. The buf portion of the WSABUF pointed to by 
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IpCallerld points to a SOCKADDR. The SOCKADDR structure is interpreted according 
to its address family (typically by casting the SOCKADDR to some type specific to the 
address family). : | 


The jJoSQOS parameter references the FLOWSPEC structures for socket s specified by 
the caller, one for each direction, followed by any additional provider-specific. 
parameters. The sending or receiving flow specification values will be ignored as 
appropriate for any unidirectional sockets. A NULL value for indicates that there is no 
caller supplied QOS and that no negotiation is possible. A non-NULL /pSQOS pointer 
indicates that a QOS negotiation is to occur or that the provider is prepared to accept the 
QOS request without negotiation. 


The /pGQOS parameter is reserved, and should be NULL. 


The /pCalleeld is a value parameter that contains the local address of the connected 
entity. The buf portion of the WSABUF pointed to by /pCallee/d points to a SOCKADDR. 
The SOCKADDR structure is interpreted according to its address family (typically by 
casting the SOCKADDR to some type specific to the address family). 


The IpCalleeData is a result parameter used by the condition function to supply user 
data back to the connecting entity. The /oCalleeData->/en initially contains the length of 
the buffer allocated by the service provider and pointed to by /pCalleeData->buf. A value 
of zero means passing user data back to the caller is not supported. The condition 
function should copy up to /oCalleeData->len bytes of data into /pCalleeData->buf, and 
then update /pCalleeData->len to indicate the actual number of bytes transferred. If no 
user data is to be passed back to the caller, the condition function should set 
loCalleeData->len to zero. The format of all address and user data is specific to the 
address family to which the socket belongs. 


The dwCallbackData parameter value passed to the condition function is the value 
passed as the dwCallbackData parameter in the original WSAAccept call. This value is 
interpreted only by the Windows Socket version 2 client. This allows a client to pass 
some context information from the WSAAccept call site through to the condition 
function. This also provides the condition function with any additional information 
required to determine whether to accept the connection or not. A typical usage is to pass 
a (Suitably cast) pointer to a data structure containing references to application-defined 
objects with which this socket is associated. 
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Version: Requires Windows Sockets 2.0. 


_ Header: Declared in Winsock2.h. 


Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, accept, bind, connect, getsockopt, listen, select, socket, 
WSAAsyncSelect, WSAConnect 
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WSAAddressToString 


The Windows Sockets WSAAddressToString function converts all components of a 
SOCKADDR structure into a human-readable string representation of the address. 


This is intended to be used mainly for display purposes. If the caller wants the translation 
to be done by a particular provider, it should supply the corresponding 
WSAPROTOCOL_INFO structure in the /pProtocolinfo parameter. 


Parameters 


IpsaAddress 
[in] Pointer to the SOCKADDR structure to translate into a string. 


dwAddressLength 
[in] Length of the address | in SOCKADDR, which may vary in size with different 
protocols. 


loProtocollinfo 
[in] (Optional) The WSAPROTOCOL_ INFO structure for a particular provider. If this is is 
NULL, the call is routed to the provider of the first protocol Supporting the address 
family indicated in /psaAddress. 


loszAddressString 
[in] Buffer that receives the human-readable address string. 


lpdwAddressStringLength 
[in/out] On input, the length of the AddressString buffer. On output, returns the length 
of the string actually copied into the buffer. If the supplied buffer is not large enough, 
the function fails with a specific error of WSAEFAULT and this patainete! is updated 
with the required size in bytes. 


Return Values s | 

If no error occurs, WSAAddressToString returns a value of zero. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling | 
.WSAGetLastError. 
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Meaning 
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Parameters 


hWnd 


[in] Handle of the window that will receive a message when the asynchronous request 


completes. 


wMsg 


[in] Message to be received when the asynchronous request completes. 
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addr 
[in] Pointer to the network address for the host. Host addresses are stored in network 
byte order. 


len 
[in] Length of the address. 

type 
[in] Type of the address. 

buf 
[out] Pointer to the data area to receive the HOSTENT data. The data area must be 
larger than the size of a HOSTENT structure because the supplied data area is used 
by Windows Sockets to contain a HOSTENT structure and all of the data referenced 
by members of the HOSTENT structure. A buffer of MAXGETHOSTSTRUCT bytes is 
recommended. | 


buflen 
lin] Size of data area for the buf parameter. 


Return Values 
The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. 


If no error occurs, WSAAsyncGetHostByAddr returns a nonzero value of type 
HANDLE that is the asynchronous task handle (not to be confused with a Windows 

_ HTASK) for the request. This value can be used in two ways. It can be used to cancel 
the operation using WSACancelAsyncRequest, or it can be used to match up 
asynchronous operations and completion mpesaces by examining the wParam message 
parameter. 


lf the asynchronous epsralion could not be initiated, WSAAsyncGetHostByAdar 
returns a zero value, and a specific error number can be retrieved by calling 
WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the /Param in the reply message using 
the WSAGETASYNCERROR macro. 


Error code Meaning 

WSAENETDOWN The network subsystem has failed. 

WSAENOBUFS Insufficient buffer space is available. 

WSAEFAULT ador or buf is not in a valid part of the process 
| , } address space. . | 

WSAHOST_NOT_FOUND ___ Authoritative answer host not found. 


WSATRY_AGAIN | Aa? Nonauthoritative host not found, or SERVERFAIL. 
7 | (continued) 
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(continued) 


Error code — Meaning 

WSANO_RECOVERY Nonrecoverable errors, FORMERR, REFUSED, 
NOTIMP. 

WSANO_DATA Valid name, no data record of requested type. 


The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 


Error Code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before 
| using this function. 

WSAENETDOWN The network subsystem has failed. | 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 

WSAEWOULDBLOCK The asynchronous operation cannot be scheduled at 


this time due to resource or other constraints within 
the Windows Sockets implementation. 


Remarks 


The WSAAsyncGetHostByAddr function is an asynchronous version of 
gethostbyaddr. It is used to retrieve the host name and address information that 
corresponds to a network address. Windows Sockets initiates the operation and returns 
to the caller immediately, passing back an opaque, asynchronous task handle that the 
application can use to identify the operation. When the operation is completed, the 
results (if any) are copied into the buffer provided by the caller and a message Is sent to 
the application’s window. 


When the asynchronous operation has completed, the application window indicated by 
the hWnd parameter receives message in the wMsg parameter. The wParam parameter 
contains the asynchronous task handle as returned by the original function call. The high 
16 bits of /Param contain any error code. The error code can be any error as defined in 
Winsock2.h. An error code of zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
HOSTENT structure. To access the members of this structure, the original buffer 
address is cast to a HOSTENT structure pointer and accessed as appropriate. 


lf the error code is WGAENOBUFS, the size of the buffer specified by buflen in the 
original call was too small to contain all the resulting information. In this case, the low 16 
bits of /Param contain the size of buffer required to supply all the requisite information. If 
the application decides that the partial data is inadequate, itcan reissue the 
WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the 
desired information (that is, no smaller than the low 16 bits of /Param). 


Chapter 8 Winsock 2 Functions 239 


The buffer supplied to this function is used by Windows Sockets to construct a structure 
together with the contents of data areas referenced by members of the same HOSTENT 
structure. To avoid the WSAENOBUFS error, the application should provide a buffer of 
at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h). 


The error code and buffer length should be extracted from the /Param using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h as: 


The use of these macros will maximize the portability of the source code pie the 
application. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, gethostbyaddr, HOSTENT, WSACancelAsyncRequest 


‘WSAAsyncGetHostByName 


The Windows Sockets WSAAsyncGetHostByName function Hey DenrOnous'y retrieves 
host information corresponding to a host name. 


Parameters 


hWnd 
[in] Handle of the window that will receive a message. when the asynchronous request 
completes. — 
wMsg 
[in] Message to be received when the asynchronous request completes. 
name 
[in] Pointer to the null-terminated name of the host. 
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buf 
[out] Pointer to the data area to receive the HOSTENT data. The data area must be 
larger than the size of a HOSTENT structure because the supplied data area is used 
by Windows Sockets to contain a HOSTENT structure and all of the data referenced 
by members of the HOSTENT structure. A buffer of MAXGETHOSTSTRUCT bytes is 
recommended. | 


buflen 
[in] Size of data area for the buf parameter. 


Return Values 


The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. 


If no error occurs, WSAAsyncGetHostByName returns a nonzero value of type 
HANDLE that is the asynchronous task handle (not to be confused with a Windows 
HTASk) for the request. This value can be used in two ways. It can be used to cancel 
the operation using WSACancelAsyncRequest, or it can be used to match up 
asynchronous operations and completion messages by examining the wParam message 
parameter. 


lf the asynchronous operation could not be initiated, WSAAsyncGetHostByName 
returns a zero value, and a specific error number can be retrieved by calling 
WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the /Param in the reply message using 
the WSAGETASYNCERROR macro. 


Error code Meaning 

WSAENETDOWN The network subsystem has failed. 

WSAENOBUFS Insufficient buffer space is available. 

WSAEFAULT The name or buf parameter is not in a valid Lean of 

| the process address space. 

WSAHOST_NOT_FOUND Authoritative answer host not found. 

WSATRY_AGAIN A nonauthoritative host not found, or SERVERFAIL. 

WSANO_RECOVERY Nonrecoverable errors, FORMERR, REFUSED, 
NOTIMP. 


WSANO_DATA Valid name, no data record of auenied pe: 


The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. | 

WSAEWOULDBLOCK | The asynchronous operation cannot be scheduled at 


this time due to resource or other constraints within 
the Windows Sockets implementation. 


Remarks 

The WSAAsyncGetHostByName function is an asynchronous version of 
gethostbyname, and is used to retrieve host name and address information 
corresponding to a host name. Windows Sockets initiates the operation and returns to 
the caller immediately, passing back an opaque asynchronous task handle that which 
the application can use to identify the operation. When the operation is completed, the 
results (if any) are copied into the buffer provided by the caller and a message is sent to 
the application’s window. 


When the asynchronous operation has completed, the application window indicated by 
the hWnd parameter receives message in the wMsg parameter. The wParam parameter 
contains the asynchronous task handle as returned by the original function call. The high 
16 bits of /Param contain any error code. The error code can be any error as defined in 
Winsock2.h. An error code of zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
HOSTENT structure. To access the elements of this structure, the original buffer address 
should be cast to a HOSTENT structure pointer and accessed as appropriate. 


lf the error code is WSAENOBUFS, the size of the buffer specified by buflen in the 
original call was too small to contain all the resulting information. In this case, the low 
16 bits of /Param contain the size of buffer required to supply all the requisite 
information. If the application decides that the partial data is inadequate, it can reissue 
the WSAAsyncGetHostByAddr function call with a buffer large enough to receive all 
the desired information (that is, no smaller than the low 16 bits of /Param). 


The buffer supplied to this function is used by Windows Sockets to construct a 
HOSTENT structure together with the contents of data areas referenced by members of 
the same HOSTENT structure. To avoid the WSAENOBUFS error, the application 
should provide a buffer of at least MAXGETHOSTSTRUCT bytes - defined in 
Winsock2.h). | 


The error code and buffer length should be extracted from the /Param using the macros 
WSAGETASYNCERFOR and WSAGETASYNCBUFLEN, defined in Winsocka. h as: 
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wMsg 


[in] Message to be receive 


name 


synchronous request completes. 


d when the as 


[in] Pointer to the null-terminated protocol name to be resolved. | 
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buf 
[out] Pointer to the data area to receive the PROTOENT data. The data area must be 
larger than the size of a PROTOENT structure because the data area is used by 
Windows Sockets to contain a PROTOENT structure and all of the data that is 
referenced by members of the PROTOENT structure. A buffer of 
MAXGETHOSTSTRUCT bytes is recommended. | 


buflen 
[out] Size of data area for the buf parameter. 


Return Values 
The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. 


If no error occurs, WSAAsyncGetProtoByName returns a nonzero value of type 
HANDLE that is the asynchronous task handle for the request (not to be confused with a 
Windows HTASKk). This value can be used in two ways. It can be used to cancel the 
operation using WSACancelAsyncRequest, or it can be used to matchup | 
asynchronous operations and completion messages, by examining the wParam 
message parameter. 


If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName 
returns a zero value, anda specific error number can be retrieved by calling 
WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the /Param in the Fepyy message using | 
~ the WSAGETASYNCERROR macro. 


Error code ‘Meaning 

WSAENETDOWN The network subsystem has failed. 
WSAENOBUFS | Insufficient buffer space is available. 
WSAEFAULT The name or buf parameter is not in a valid part of 

} | | the process address space. © 
WSAHOST_NOT_FOUND _ Authoritative answer protocol not found. 
WSATRY_AGAIN | A nonauthoritative weiss not found, or server 
‘sn oe SSS : failure. 
WSANO_RECOVERY | Nonrecoverable errors, the protocols database is not 
i eo peo — accessible. i 

| WSANO_ erie wae Valid name, no data record of requested type. 


~The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. , 
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Error code , Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. | 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS _ A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 

WSAEWOULDBLOCK The asynchronous operation cannot be scheduled at 


this time due to resource or other constraints within 
the Windows Sockets implementation. 


Remarks 


The WSAAsyncGetProtoByName function is an asynchronous version of 
getprotobyname. It is used to retrieve the protocol name and number from the Windows 
Sockets database corresponding to a given protocol name. Windows Sockets initiates 
the operation and returns to the caller immediately, passing back an opaque, 
asynchronous task handle that the application can use to identify the operation. When 
the operation is completed, the results (if any) are copied into the buffer provided by the 
caller and a message is sent to the application’s window. 


When the asynchronous operation has completed, the application window indicated by 
the hWnd parameter receives message in the wMsg parameter. The wParam parameter 
contains the asynchronous task handle as returned by the original function call. The high 
16 bits of /Param contain any error code. The error code can be any error as defined in 
Winsock2.h. An error code of zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
PROTOENT structure. To access the members of this structure, the original buffer 
address should be cast to a PROTOENT structure pointer and accessed as appropriate. 


If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the 
original call was too small to contain all the resulting information. In this case, the low 16 
bits of /Param contain the size of buffer required to supply all the requisite information. If 
the application decides that the partial data is inadequate, it can reissue the 
WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the 
desired information (that is, no smaller than the low 16 bits of /Param). 


The buffer supplied to this function is used by Windows Sockets to construct a 
PROTOENT structure together with the contents of data areas referenced by members 
of the same PROTOENT structure. To avoid the WSAENOBUFS error noted above, the 

~ application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined 
in Winsock2.h). 7 | 3 | 


The error code and buffer length should be extracted from the /Param using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUEFLEN, defined in Winsock2.h as: 
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The use of these macros will maximize the portability of the source code for the 
application. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
. Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, getprotobyname, WSACancelAsyncRequest 


WSAAsyncGetProtoByNumber 


The Windows Sockets WSAAsyncGetProtoByNumber function asynchronously 
retrieves protocol information corresponding to a protocol number. 


Parameters 


hWnd 
[in] Handle of the window that will receive a message when the asynchronous request 
completes. 


wMsg | | | 
[in] Message to be received when the asynchronous request completes. : 


number a | | 
[in] Protocol number to be resolved, in host byte order. 


buf 
[out] Pointer to the data area to receive the PROTOENT data. The data area must be 
- larger than the size of a PROTOENT structure because the data area is used by | 
Windows Sockets to contain a PROTOENT structure and all of the data that is 
referenced by members of the PROTOENT structure. A buffer of 
~MAXGETHOSTSTRUCT bytes is recommended. 
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buflen | 
[in] size of data area for the buf parameter. | 


Return Values 


The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. - 


If no error occurs, WSAAsyncGetProtoByNumber returns a nonzero value of type 
HANDLE that is the asynchronous task handle for the request (not to be confused with a 
Windows HTASK). This value can be used in two ways. It can be used to cancel the 
operation using WSACancelAsyncRequest, or it can be used to match up 
asynchronous operations and completion messages, by examining the wParam 
message parameter. 


If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumber 
returns a zero value, and a specific error number can be retrieved by calling 
WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the /Param in the reply message using 
the WSAGETASYNCERROR macro. 


Error code | Meaning 
WSAENETDOWN The network subsystem has failed. 

WSAENOBUFS , Insufficient buffer space is available. 

WSAEFAULT | The buf parameter is not in a valid part of the process 


address space. 
WSAHOST_NOT_FOUND Authoritative answer protocol not found. 


WSATRY_AGAIN Nonauthoritative protocol not found, or server failure. 

WSANO_ RECOVERY Nonrecoverable errors, the protocols database is not 
accessible. | 

WSANO_DATA Valid name, no data record of requested type. 


The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. | 


Error code Peay Meaning 

WSANOTINITIALISED _ A successful WSAStartup call must occur before using 
| | this function. 

WSAENETDOWN _ The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or 


the service provider is still processing a callback function. 


WSAEWOULDBLOCK The asynchronous operation cannot be scheduled at this 
time due to resource or other constraints within the 
Windows Sockets implementation. 
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Remarks 


The WSAAsyncGetProtoByNumber function is an asynchronous version of 

getprotobynumber, and is used to retrieve the protocol name and number 

corresponding to a protocol number. Windows Sockets initiates the operation and 

returns to the caller immediately, passing back an opaque, asynchronous task handle 

that the application can use to identify the operation. When the operation is completed, 

the results (if any) are copied into the buffer provided by the caller and a message is _ 
sent to the application’s window. 


When the asynchronous operation has completed, the application window indicated by 

the hWnd parameter receives message in the wMsg parameter. The wParam parameter 

contains the asynchronous task handle as returned by the original function call. The high 

16 bits of /Param contain any error code. The error code can be any error as defined in 

Winsock2.h. An error code of Zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
PROTOENT structure. To access the members of this structure, the original buffer 
address is cast to a PROTOENT structure pointer and accessed as appropriate. 


If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the 

original call was too small to contain all the resulting information. In this case, the low 16 

bits of /Param contain the size of buffer required to supply all the requisite information. If 

the application decides that the partial data is inadequate, it can reissue the - 

WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the 
desired information (that is, no smaller than the low 16 bits of [Param). 


The buffer supplied to this function is used by Windows Sockets to construct a 
PROTOENT structure together with the contents of data areas referenced by members 
of the same PROTOENT structure. To avoid the WSAENOBUFS error noted above, the 
application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined 
in Winsock2.h). 


The error code and buffer length should be extracted from the /Param using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h as: 


The use of these macros will maximize the portability of the source code for the 
application. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, getprotobynumber, WSACancelAsyncRequest 


WSAAsyncGetServByName 


The Windows Sockets WSAAsyncGetServByName function asynchronously retrieves 
service information corresponding to a service name and port. 


Parameters 


hWnd | : 
[in] Handle of the window that should receive a message when the asynchronous 
request completes. | 


wMsg 
[in] Message to be received when the asynchronous request completes. 


name | | | 
[in] Pointer to a null-terminated service name. 


proto 
[in] Pointer to a protocol name. This can be NULL, in which case 
WSAAsyncGetServByName will search for the first service entry for which s_name 
or one of the s_aliases matches the given name. Otherwise, 
WSAAsyncGetServByName matches both name and proto. 


buf 
[out] Pointer to the data area to receive the SERVENT data. The data area must be 
larger than the size of a SERVENT structure because the data area supplied is used 
by Windows Sockets to contain a SERVENT structure and all of the data that is 
referenced by members of the SERVENT structure. A buffer of 
MAXGETHOSTSTRUCT bytes is recommended. 


buflen | 
[in] Size of data area for the buf parameter. 
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Return Values 


The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. 


If no error occurs, WSAAsyncGetServByName returns a nonzero value of type 
HANDLE that is the asynchronous task handle for the request (not to be confused with a 
Windows HTASK). This value can be used in two ways. It can be used to cancel the 
operation using WSACancelAsyncRequest, or it can be used to match up 
asynchronous operations and completion messages, by sneeine the wParam 
message parameter. 


If the asynchronous operation could not be initiated, WSAAsyncServByName returns a 
zero value, and a specific error number can be retrieved by calling WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the /Param in the reply message using 
the WSAGETASYNCERROR macro. | 


Error code Meaning | 
WSAENETDOWN The network subsystem has failed. 
~WSAENOBUFS Insufficient buffer space is available. 
WSAEFAULT | buf is not in a valid Part of the process address 
space. 
WSAHOST_NOT_FOUND Authoritative answer host not found. 
WSATRY_AGAIN Nonauthoritative service not found, or server failure. 
~WSANO_RECOVERY Nonrecoverable errors, the services database is not 
ie oe accessible. , | | 
WSANO_DATA Valid name, no data record of requested type. 


The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 


Error code Meaning 
WSANOTINITIALISED A successful cea ak call must occur before 
af using this function. | 
_~WSAENETDOWN — The network subsystem has failed. 
~ WSAEINPROGRESS ~ A blocking Windows Sockets 1.1 call is in progress, 
or the service provider i is still processing a Callback 
? function. 
WSAEWOULDBLOCK The asynchronous operation cannot be scheduled at 


this time due to resource or other constraints within 
the Windows Sockets implementation. 
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Remarks 


The WSAAsyncGetServByName function is an asynchronous version of 
getservbyname and is used to retrieve service information corresponding to a service 


name. Windows Sockets initiates the operation and returns to the caller immediately, 


passing back an opaque, asynchronous task handle that the application can use to 
identify the operation. When the operation is completed, the results (if any) are copied 
into the buffer provided by the caller and a message is sent to the application’s window. 


When the asynchronous operation has completed, the application window indicated by 
the hWnd parameter receives message in the wMsg parameter. The wParam parameter 
contains the asynchronous task handle as returned by the original function call. The high 
16 bits of /Param contain any error code. The error code can be any error as defined in 
Winsock2.h. An error code of zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
SERVENT structure. To access the members of this structure, the original buffer 
address should be cast to a SERVENT structure pointer and accessed as appropriate. 


If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the 
original call was too small to contain all the resulting information. In this case, the low 16 
bits of /Param contain the size of buffer required to supply all the requisite information. If 
the application decides that the partial data is inadequate, it can reissue the 
WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the 
desired information (that is, no smaller than the low 16 bits of /Param). 


The buffer supplied to this function is used by Windows Sockets to construct a 
SERVENT structure together with the contents of data areas referenced by members of 
the same SERVENT structure. To avoid the WSAENOBUFS error, the application 
should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in 
Winsock2.h). 


The error code and buffer length should be extracted from the /Param using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUEFLEN, defined in Winsock2.h as: 


The use of these macros will maximize the portability of the source code for the 
application. | | 


Version: Requires Windows Sockets 1.1 or later. 
-Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. | 
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WSAAsyncGetServByPort | 


The Windows Sockets WSAAsyncGetServByPort function gets service information 
corresponding to a port and protocol asynchronously. 


[in] Handle of the window that should receive a message when the asynchronous 
request completes. | | 


wMsg 
[in] Message to be received when the asynchronous request completes. 


port 
[in] Port for the service, in network byte order. 


proto 
[in] Pointer to a protocol name. This can be NULL, in which case 


WSAAsyncGetServByPort will search for the first service entry for which s_port 
match the given port. Otherwise, WSAAsyncGetServByPort matches both port and 


proto. eS | | 


buf 
[out] Pointer to the data area to receive the SERVENT data. The data area must be 


larger than the size of a SERVENT structure because the data area supplied is used 

by Windows Sockets to contain a SERVENT structure and all of the data that is 
referenced by members of the SERVENT structure. A buffer of 
MAXGETHOSTSTRUCT bytes is recommended. | 


buflen | 
[in] Size of data area for the buf parameter. 
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Return Values 


The return value specifies whether or not the asynchronous operation was successfully 
initiated. It does not imply success or failure of the operation itself. 


If no error occurs, WSAAsyncGetServByPort returns a nonzero value of type HANDLE 
that is the asynchronous task handle for the request (not to be confused with a Windows 
HTASK). This value can be used in two ways. It can be used to cancel the operation 
using WSACancelAsyncRequest, or it can be used to match up asynchronous 
operations and completion messages, by examining the wParam message parameter. 


If the asynchronous operation could not be initiated, WSAAsyncGetServByPort returns 
a zero value, and a specific error number can be retrieved by calling WSAGetLastError. 


The following error codes can be set when an application window receives a message. 
As described above, they can be extracted from the [Param | in the reply message using 
the WSAGETASYNCERROR macro. 


Error code Meaning 

WSAENETDOWN The network subsystem has failed. 

WSAENOBUFS Insufficient buffer space is available. 

WSAEFAULT proto or buf is not in a valid part of the process address 
space. 

WSAHOST_NOT_FOUND Authoritative answer port not found. 

WSATRY_AGAIN Nonauthoritative port not found, or server failure. 

WSANO_RECOVERY Nonrecoverable errors, the services database is not 
accessible. 

WSANO_DATA Valid name, no data record of requested type. 


The following errors can occur at the time of the function call, and indicate that the 
asynchronous operation could not be initiated. 


Error code Meaning | 

WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS| A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 

WSAEWOULDBLOCK The asynchronous operation cannot be scheduled at this 


time due to resource or other constraints within the 
Windows Sockets implementation. 
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Remarks 


The WSAAsyncGetServByPort function is an asynchronous version of getservbyport, 
and is used to retrieve service information corresponding to a port number. Windows. 
Sockets initiates the operation and returns to the caller immediately, passing back an 
Opaque, asynchronous task handle that the application can use to identify the operation. 
When the operation is completed, the results (if any) are copied into the buffer provided 
by the caller and a message is sent to the application’s window. 


When the asynchronous operation has completed, the application window indicated by 
the hWnd parameter receives message in the wMsg parameter. The wParam parameter 
contains the asynchronous task handle as returned by the original function call. The high 
16 bits of /Param contain any error code. The error code can be any error as defined in 
Winsock2.h. An error code of zero indicates successful completion of the asynchronous 
operation. 


On successful completion, the buffer supplied to the original function call contains a 
SERVENT structure. To access the members of this structure, the original buffer 
address should be cast to a SERVENT structure pointer and accessed as appropriate. 


lf the error code is WSAENOBUFS, the size of the buffer specified by buflen in the 
original call was too small to contain all the resulting information. In this case, the low 16 
bits of /Param contain the size of buffer required to supply all the requisite information. If 
the application decides that the partial data is inadequate, it can reissue the 
WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the 
desired information (that is, no smaller than the low 16 bits of /Param). : 


The buffer supplied to this function is used by Windows Sockets to construct a 
SERVENT structure together with the contents of data areas referenced by members of 
the same SERVENT structure. To avoid the WSAENOBUFS error, the application 
should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in 
Winsock2.h). 7 


The error code and buffer length should be extracted from the paar using the macros 
WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h as: 


The use of these macros will maximize the portability of the source code for the 
| application. | 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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WSAAsyncSelect 


The Windows Sockets WSAAsyncSelect function requests Windows message-based 
notification of network events for a socket. | 


Parameters 
S 


[in] Descriptor identifying the socket for which event notification is required. 


hWnd , 
[in] Handle identifying the window that will receive a message when a network event 


occurs. 


WwMsg | 
[in] Message to be received when a network event occurs. 


[Event 
[in] Bitmask that specifies a combination of network events in which the application is 


interested. 


Return Values 

If the WSAAsyncSelect function succeeds, the return value is zero provided the 
application’s declaration of interest in the network event set was successful. Otherwise, 
the value SOCKET_ERROR is returned, and a specific error number can be retrieved by 
calling WSAGetLastError. 


Error code © Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
| function. | 

WSAENETDOWN ___— The network subsystem has failed. 

WSAEINVAL Indicates that one of the specified parameters was invalid 


such as the window handle not referring to an existing 
window, or the specified socket is in an invalid state. 
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Error code Meaning 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 

WSAENOTSOCK The descriptor is not a socket. 


Additional error codes can be set when an application window receives a message. This 
error code is extracted from the /Param in the reply message using the 
WSAGETSELECTERROR macro. Possible error codes for each network event are 
shown in the following table. 


Event: FD CONNECT 


Error code Meaning 


WSAEAFNOSUPPORT Addresses in the specified family cannot be used with 
this socket. | | 

WSAECONNREFUSED The attempt to connect was forcefully rejected. 

WSAENETUNREACH The network cannot be reached from this host at this 
time. | 

WSAEFAULT | The namelen parameter is incorrect. 

WSAEINVAL The socket is already bound to an address. 

WSAEISCONN The socket is already connected. 

WSAEMFILE | No more file descriptors are available. _ 

WSAENOBUFS — No buffer space is available. The socket cannot be 

? connected. ! 

WSAENOTCONN The socket is not connected. | 

WSAETIMEDOUT Attempt to connect timed out without establishing a 
connection. | 


Event: FD_CLOSE 


Error code — Meaning | 
~ WSAENETDOWN The network subsystem has failed. 
~WSAECONNRESET . _ The connection was reset by the remote side. 


WSAECONNABORTED The connection was terminated due to a time- out! or 
| | a other failure. 
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Event: FD_READ 
Event: FD_WRITE — 
- Event: FD_OOB 
Event: FD_ACCEPT 
Event: FD_QOS | 
Event: FD_GROUP_QOS 
Event: FD_ADDRESS_LIST_CHANGE 


Error code Meaning 

WSAENETDOWN The network subsystem has failed. 

Event: FD_ROUTING_INTERFACE_CHANGE 

Error code Meaning 

WSAENETUNREACH The specified destination is no longer reachable. 
WSAENETDOWN The network subsystem has failed. 

Remarks 


The WSAAsyncSelect function is used to request that Ws2_32.dll should send a 
message to the window hWnd whenever it detects any of the network events specified 
by the /Event parameter. The message that should be sent is specified by the wMsg 
parameter. The socket for which notification is required is identified by the s parameter. 


The WSAAsyncSelect function automatically sets socket s to nonblocking mode, 
regardless of the value of /Event. See the foctlsocket functions for information on how 
to set the nonblocking socket back to blocking mode. 


The /Event parameter is constructed by using the bitwise OR operator with any of the 
values specified in the following table. | 


Value Meaning 

FD_READ : Wants to receive notification of readiness for reading. 

FD_WRITE Wants to receive notification of readiness for writing. 

FD_OOB Wants to receive notification of the arrival of OOB data. 

FD_ACCEPT Wants to receive notification of incoming connections. 

FD_CONNECT Wants to receive notification of completed connection or 
| | multipoint join operation. 

FD_CLOSE Wants to receive notification of socket closure. 


FD_QOS Wants to receive notification of socket Quality of Service 
| (QOS) changes. 
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Value Meaning 

FD_GROUP_QOS Reserved. 

FD_ROUTING_ Wants to receive notification of routing interface changes 
INTERFACE_CHANGE for the specified destination(s). 

FD_ADDRESS_ Wants to receive notification of local address list changes 
LIST_CHANGE for the socket’s protocol family. 


Issuing a WSAAsyncSelect for a socket cancels any previous WSAAsyncSelect or 
WSAEventSelect for the same socket. For example, to receive notification for both 
reading and writing, the application must call WSAAsyncSelect with both FD_READ 
and FD_WRITE, as follows: 


It is not possible to specify different messages for different events. The following code 
will not work; the second call will cancel the effects of the first, and only FD_WRITE 
events will be reported with message wMsg2: 


To cancel all notification indicating tr that Windows Sockets should send no further 
messages related to network events on the socket, [Event is set to zero. 


Although WSAAsyncSelect immediately disables event message posting for the socket 
in this instance, it is possible that messages could be waiting in the application’s 
message queue. Therefore, the application must be prepared to receive network event 
messages even after cancellation. Closing a socket with closesocket also cancels 
WSAAsyncSelect message sending, but the same caveat about messages in the 
queue still applies. 


The socket created by the accept function has the same properties as the listening 
socket used to accept it. Consequently, WSAAsyncSelect events set for the listening 
socket also apply to the accepted socket. For example, if a listening socket has 
~WSAAsyncSelect events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket 
accepted on that listening socket will also have FD_ACCEPT, FD_READ, and 
_ FD_WRITE events with the same wMsg value used for messages. If a different wMsg or 
~ events are desired, the application should call WSAAsyncSelect, passing the accepted 
socket and the desired new information. 


When one of the nominated network events occurs on the specified socket s, the 
application’s window hWnd receives message wMsg. The wParam parameter identifies 
the socket on which a network event has occurred. The low word of /Param specifies the 
network event that has occurred. The high word of [Param contains any error code. The 

_ error code be any error as defined in Winsocke. h. 
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Note Upon receipt of an event notification message, the WSAGetLastError function 
cannot be used to check the error value because the error value returned can differ from 
the value in the high word of /Param. 


The error and event codes can be extracted from the /Param using the macros 
WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in Winsock2.h as: 


The use of these macros will maximize the portability of the source code for the 
application. 


The possible network event codes that can be returned are shown in the following table. 


Value Meaning 

FD_READ Socket s ready for reading. 

FD_WRITE Socket s ready for writing. 

FD_OOB OOB data ready for reading on socket s. 

FD_ACCEPT Socket s ready for accepting a new incoming connection. 

FD_CONNECT : Connection or multipoint join operation initiated on socket s 
completed. 

FD_CLOSE Connection identified by socket s has been closed. 

FD_QOS | Quality of Service associated with socket s has changed. 

FD_GROUP_QOS Reserved. 

FD_ROUTING_ | Local interface that should be used to send to the specified 

INTERFACE_CHANGE destination has changed. 

FD_ADDRESS_ The list of addresses of the socket’s protocol family to which 

LIST_CHANGE the application client can bind has changed. 


Although WSAAsyncSelect can be called with interest in multiple events, the application 
window will receive a single message for each network event. 


As in the case of the select function, WSAAsyncSelect will frequently be used to 
determine when a data transfer operation (send or recv) can be issued with the 
expectation of immediate success. Nevertheless, a robust application must be prepared 
for the possibility that it can receive a message and issue a Windows Sockets 2 call that 
returns WSAEWOULDBLOCK immediately. For example, the following sequence of 
events is possible: 


1. Data arrives on socket s; Windows Sockets 2 posts WSAAsyncSelect message 


2. Application processes some other message 


3. While processing, application issues an ioctlsocket(s, FIONREAD.. ) and notices 
that there is data ready to be read 
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4. Application issues a recv(s,...) to read the data 


5. Application loops to process next message, eventually reaching the 
WSAAsyncSelect message indicating that data is ready to read 


6. Application issues recv(s,...), which fails with the error WSAEWOULDBLOCK. 


Other sequences are possible. 


The Ws2_32.dll will not continually flood an application with messages for a particular 
network event. Having successfully posted notification of a particular event to an 
application window, no further message(s) for that network event will be posted to the © 
application window until the application makes the function call that implicitly reenables 
notification of that network event. 


Event | Reenabling function 

FD_READ recv, recvfrom, WSARecv, or WSARecvFrom. 
FD_WRITE send, sendto, WSASend, or WSASendTo. 
FD_OOB recv, recvfrom, WSARecv, or WSARecvFrom. 
FD_ACCEPT accept or WSAAccept unless the error code is 


WSATRY_AGAIN indicating that the condition function 
returned CF_DEFER. 


FD_CONNECT NONE. 

FD_CLOSE NONE. 

FD_QOS | WSAloctl with command SIO_GET_QOS. 
FD_GROUP_QOS Reserved. 

FD_ROUTING_ | WSAloctl with command 

INTERFACE_CHANGE SIO_ROUTING_INTERFACE_CHANGE. 

FD_ADDRESS _ WSAloctl with command SIO_ADDRESS_LIST_CHANGE. 
LIST_CHANGE 


Any call to the reenabling routine, even one that fails, results in reenabling of message 
posting for the relevant event. 


For FD_READ, FD_OOB, and FD _ACCEPT events, message posting is pve -triggered. 
This means that if the reenabling routine is called and the relevant condition is still met 
after the call, a WSAAsyncSelect message is posted to the application. This allows an 
application to be event-driven and not be concerned with the amount of data that arrives 
at any one time. Consider the following sequence: | 


1. Network transport stack receives 100 bytes of data on socket s and. causes Windows | 
_ Sockets 2 to post an FD_READ message. 3 

2. The application issues recv( s, buffptr, 50, 0) to read 50 bytes. 

3. Another FD_READ message is posted since there is still data to be read. 
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With these semantics, an application need not read all available data in response to an 
FD_READ message—a single recv in response to each FD_READ message is 
appropriate. If an application issues multiple recv calls in response to a single 
FD_READ, it can receive multiple FD_READ messages. Such an application can need 
to disable FD_READ messages before starting the recv calls by calling 
WSAAsyncSelect with the FD_READ event not set. 


The FD_QOS and FD_GROUP_QOS events are considered edge triggered. A message 
will be posted exactly once when a quality of service change occurs. Further messages 
will not be forthcoming until either the provider detects a further change in quality of 
service or the application renegotiates the quality of service for the socket. 


The FD_LROUTING_INTERFACE_CHANGE message is posted when the local interface 
that should be used to reach the destination specified in WSAloctl with 
SIO_ROUTING_INTERFACE_CHANGE changes after such IOCTL has been issued. 


The FD_ADDRESS_LIST_CHANGE message is posted when the list of addresses t to 
which the application can bind changes after WSAloctil with 
SIO_ADDRESS_LIST_CHANGE has been issued. 


If any event has already happened when the application calls WSAAsyncSelect or 
when the reenabling function is called, then a message is posted as appropriate. For 
example, consider the following sequence: 


1. An application calls listen. 
2. A connect request is received but not yet accepted. 


3. The application calls WSAAsyncSelect specifying that it wants to receive 
FD_ACCEPT messages for the socket. Due to the persistence of events, Windows 
Sockets 2 posts an FD_ACCEPT message immediately. 


The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted 
when a socket is first connected with connect or WSAConnect (after FD_CONNECT, if 
also registered) or accepted with accept or WSAAccept, and then after a send 
operation fails with WSAEWOULDBLOCK and buffer space becomes available. 
Therefore, an application can assume that sends are possible starting from the first 
FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such 
a failure the a aad will be notified that sends are again possible with an FD_WRITE 
message. 


The FD_OOB event is used only when a ene is configured to receive OOB data 
separately. (See section DECnet Out-Of-band data for a discussion of this topic.) If the 
socket is configured to receive OOB data inline, the OOB (expedited) data is treated as 
normal data and the application should register an interest in, and will receive, - 
FD_READ events, not FD_OOB events. An application can set or inspect the way in 
which OOB data is to be handled by using peteocnert or getsockopt for the 
SO_OOBINLINE option. 


Chapter 8 Winsock 2 Functions 261 


The error code in an FD_CLOSE message indicates whether the socket close was 
graceful or abortive. If the error code is zero, then the close was graceful; if the error 
code is WSAECONNRESET, then the socket’s virtual circuit was reset. This only applies 
to connection-oriented sockets such as SOCK_STREAM. 


The FD_CLOSE message is posted when a close indication is received for the virtual 
circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is 
posted when the connection goes into the TIME WAIT or CLOSE WAIT states. This 
results from the remote end performing a shutdown on the send side or a closesocket. 
FD_CLOSE should only be posted after all data is read from a socket, but an application 
should check for remaining data upon receipt of FD_CLOSE to avoid any possibility of 
losing data. 


Please note your application will receive ONLY an FD_CLOSE message to indicate 
closure of a virtual circuit, and only when all the received data has been read if this is a 
graceful close. It will not receive an FD_READ message to indicate this condition. 


The FD_QOS message is posted when any parameter in the flow specification 
associated with socket s has changed. Applications should use WSAloctl with command 
SIO_GET_QOS to get the current QOS for socket s. 


The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events 
are considered edge triggered as well. A message will be posted exactly once when a 
change occurs after the application has requested the notification by issuing WSAloctl 
with SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE 
correspondingly. Further messages will not be forthcoming until the application reissues 
the IOCTL and another change is detected since the IOCTL has been issued. 


Here is a summary of events and conditions for each asynchronous notification 
message. 
e FD_READ: 
1. When WSAAsyncSelect is called, if there is data currently available to receive. 
2. When data arrives, if FD_READ is not already posted. 
3. After recv or recvfrom is called (with or without MSG PEN, if data is still 
available to receive. 
Note When setsockopt SO_OOBINLINE is enabled, data includes both normal 
data and OOB data in the instances noted above. 
e FD_WRITE: 
1. When WSAAsyncSelect called, if a send or sendto is possible. 
2. After connect or accept called, when connection established. 
3. After send or sendto fail with WGAEWOULDBLOCK, when send or sendto are 
likely to succeed. 


4. After bind on a connectionless socket. FD_WRITE may or may not occur at this 
time (implementation-dependent). In any case, a connectionless socket is always 
writeable immediately after a bind operation. 
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e FD_OOB: Only valid when setsockopt SO_OOBINLINE is disabled (default). 


1. When WSAAsyncSelect called, if there is OOB data oe available to receive 
with the MSG_OOB flag. 


2. When OOB data arrives, if FD_OOB not already posted. 


3. After recv or recvfrom called with or without MSG_OOB flag, if OOB data is still 
available to receive. | 


FD_ACCEPT: 

1. When WSAAsyncSelect called, if there is currently a connection request available 
to accept. 

2. When a connection request arrives, if FD_ACCEPT not already posted. | 

3. After accept called, if there is another connection request available to accept. 

FD_CONNECT: 

1. When WSAAsyncSelect called, if there is currently a connection established. 

2. After connect called, when connection is established (even when connect 
succeeds immediately, as is typical with a datagram socket). 

3. After calling WSAJoinLeaf, when join operation completes. 

4. After connect, WSAConnect, or WSAJoinLeaf was called with a nonblocking, 
connection-oriented socket. The initial operation returned with a specific error of 
WSAEWOULDBLOCK, but the network operation went ahead. Whether the 
operation eventually succeeds or not, when the outcome has been determined, 


FD_CONNECT happens. The client should check the error code to determine 
whether the outcome was successful or failed. 


FD_CLOSE: Only valid on connection-oriented sockets (for example, 

SOCK_STREAM) 

1. When WSAAsyncSelect called, if socket connection has been closed. 

2. After remote system initiated graceful close, when no data currently available to 
receive (note: if data has been received and is waiting to be read when the remote 
system initiates a graceful close, the FD_CLOSE is not delivered until all pending 
data has been read). | 

3. After local system initiates graceful close with shutdown and remote system has 
responded with “End of Data” notification (for pone TCP FIN), when no data 
currently available to receive. 


4. When remote system terminates connection (for example, sent TCP RST), and 
[Param will contain WSAECONNRESET error value. 


Note FD_CLOSE is not posted after closesocket is called. 


FD_QOS: 
1. When WSAAsyncSelect called, if the quality of service associated with the socket 


has been changed. 


2. After WSAloctl with SIO_GET_QOS called, when the quality of service is changed. 
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e FD GROUP_QOS Reserved. 
e FD _ROUTING_INTERFACE_CHANGE: 


After WSAloctl with SIO_ROUTING_INTERFACE_CHANGE called, when the local 
interface that should be used to reach the destination specified in the IOCTL changes. 


e FD_ADDRESS_LIST_CHANGE: 


After WSAloctl with SIO_ADDRESS_LIST_CHANGE called, when the list of local 
addresses to which the application can bind changes. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows he 
Extension Functions, select, WSAEventSelect 


WSACancelAsyncRed vest 


The Windows Sockets WSACancelAsyncRequest function cancels an 1 incomplete 
asynchronous operation. 


Parameters 


hAsyncTaskHandle 
[in] Handle that specifies the asynchronous operation to be canceled. 


Return Values 

The value returned by WSACancelAsyncRequest is zero if the operation was 

successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a 
_ specific error number can be retrieved by calling WSAGetLastError. _ | 


Error code | Meaning | “ae 
-WSANOTINITIALISED — A successful WSAStartup call must occur before using this 
. function. | 
WSAENETDOWN The network subsystem has failed. - 
WSAEINVAL | Indicates that the specified asynchronous task handle was 
a - invalid. 


(continued) 
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(continued) 
Error code Meaning © 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
| service provider is still processing a callback function. 
WSAEALREADY _ The asynchronous routine being canceled has already 
completed. 


Note It is unclear whether the application can usefully distinguish between 
WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is 
no asynchronous operation in progress with the indicated handle. [Trivial exception: zero 
is always an invalid asynchronous task handle.] The Windows Sockets specification 
does not prescribe how a conformant Windows Sockets provider should distinguish 
between the two cases. For maximum portability, a Windows Sockets application should 
treat the two errors as equivalent. 


Remarks 


The WSACancelAsyncRequest function is used to cancel an asynchronous operation 
that was initiated by one of the WSAAsyncGetXByY functions such as 
WSAAsyncGetHostByName. The operation to be canceled is identified by the 

hAsync TaskHandle parameter, which should be set to the asynchronous task handle as 
returned by the initiating WSAAsyncGetXByY function. 


An attempt to cancel an existing asynchronous WSAAsyncGetXByyY operation can fail 
with an error code of WSAEALREADY for two reasons. First, the original operation has 
already completed and the application has dealt with the resultant message. Second, the 
original operation has already completed but the resultant message is still waiting in the 
application window queue. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSAAsyncGetHostByAddr, WSAAsyncGetHostByName, 
WSAAsyncGetProtoByName, WSAAsyncGetProtoByNumber, 
WSAAsyncGetServByName, WSAAsyncGetServByPort 
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WSACancelBlockingCall 


The WSACancelBlockingCall function has been removed in compliance with the 
Windows Sockets 2 specification, revision 2.2.0. | 


The function is not exported directly by the Ws2_32.dIl and Windows Sockets 2 
applications should not use this function. Windows Sockets 1.1 applications that call this 
function are still supported through the Winsock.dll and Wsock32.dll. 


Blocking hooks are generally used to keep a single-threaded GUI application responsive 
during calls to blocking functions. Instead of using blocking hooks, an applications 
should use a separate thread (separate from the main GUI thread) for network activity. 


Version: Requires Windows Sockets 1.1. Obsolete for Windows $ Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


WSACleanup 


The Windows Sockets WSACleanup function terminates use of the Ws2_32.dll. 


- Parameters 
This function has no parameters. 


Return Values 


The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 
WSAGetLastError. 


Attempting to call WSACleanup from within a blocking hook and then failing to check the 
return code is a common programming error in Windows Socket 1.1 applications. If an. 
application needs to quit while a blocking call is outstanding, the application must first 
cancel the blocking call with WSACancelBlockingCall then issue the ee call 
once control has been returned to the application. 


In a multithreaded environment, WSACleanup terminates Windows Sockets operations 
for all threads. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
| | function. | | | 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 


service provider is still processing a callback function. 


Remarks 


An application or DLL is required to perform a successful WSAStartup call before it can 
use Windows Sockets services. When it has completed the use of Windows Sockets, the 
application or DLL must call WSACleanup to deregister itself from a Windows Sockets 
implementation and allow the implementation to free any resources allocated on behalf 
of the application or DLL. Any pending blocking or asynchronous calls issued by any 
thread in this process are canceled without posting any notification messages or without 
signaling any event objects. Any pending overlapped send and receive operations 
(WSASend/WSASendTo/WSARecv/WSARecvFrom with an overlapped socket) issued 
by any thread in this process are also canceled without setting the event object or 
invoking the completion routine, if specified. In this case, the pending overlapped 
operations fail with the error status WSA_OPERATION_ABORTED. 


Sockets that were open when WSACleanup was called are reset and automatically 
deallocated as if closesocket were called; sockets that have been closed with 
closesocket but that still have pending data to be sent can be affected—the pending 
data can be lost if the Ws2_32.dll is unloaded from memory as the application exits. To 
insure that all pending data is sent, an application should use shutdown to close the 
connection, then wait until the close completes before calling closesocket and 
WSACleanup. All resources and internal state, such as queued unposted-posted 
messages, must be deallocated so as to be available to the next user. 


There must be a call to WSACleanup for every successful call to WSAStartup made by 
a task. Only the final WSACleanup for that task does the actual cleanup; the preceding 
calls simply decrement an internal reference count in the Ws2_32.dlll. 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, closesocket, shutdown, WSAStartup 
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WSACloseEvent 


The Windows Sockets WSACloseEvent function closes an open event object handle. 


Parameters 


hEvent 
[in] Object handle identifying the open event. 


Return Values 
| If the function succeeds, the return value is TRUE. 


If the function fails, the return value is FALSE. To get extended error information, call 


WSAGetLastError. 

Error code Meaning 

WSANOTINITIALISED | A successful WSAStartup call must occur before 

| using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
| or the service provider | is stil processing a callback 

function. 
WSA_INVALID_HANDLE The hEvent is not a valid event object handle. 
Remarks 


The handle to the event object is closed so that further references to this handle will fail 
with the error WSA_ INVALID_HANDLE. 7 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows- -Specific 
Extension Functions, WSACreateEvent, WSAEnumNetworkEvents, 
WSAEventSelect, WSAGetOverlappedResult, WSARecv, WSARecvFrom, 
WSAResetEvent, WSASend, WSASendTo, WSASetEvent, 

yee aeoeven. 


Volume 1 Winsock and QOS 


WSAConnect ae 


The Windows Sockets WSAConnect function establishes a connection to another 
socket application, exchanges connect data, and specifies needed quality of service 
based on the supplied FLOWSPEC structure. 


Parameters | | 


Ss 
[in] Descriptor identifying an unconnected socket. 


name 
[in] Name of the socket in the other application to which to connect. 


namelen 
[in] Length of the name. 


|pCallerData 
[in] Pointer to the user data that is to be transferred to the other socket during 
connection establishment. 


lpCalleeData 
[out] Pointer to the user data that is to be transferred back from the other socke 
during connection establishment. 


IpPSQOS 
[in] Pointer to the FLOWSPEC structures for socket s, one for each direction. 


IpPGQOS 
[in] Reserved. Should be NULL. 


~ Return Values 


If no error occurs, WSAConnect returns zero. Otherwise, it returns SOCKET_ERROR, 
and a specific error code can be retrieved by calling WSAGetLastError. On a blocking 
socket, the return value indicates success or failure of the connection attempt. 


With a nonblocking socket, the connection attempt cannot be completed immediately. In 
this case, WSAConnect will return SOCKET_ERROR, and WSAGetLastError will 
return WSAEWOULDBLOCK,; the application could therefore: 


e Use select to determine the completion of the connection request by checking if the 
socket is writeable. 
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e lf your application is using WSAAsyncSelect to indicate interest in connection 
events, then your application will receive an FD_CONNECT notification when the 
connect operation is complete (successful or not). 

e lf your application is using WSAEventSelect to indicate interest in connection events, 
then the associated event object will be signaled when the connect operation is 
complete (successful or not). 


For a nonblocking socket, until the connection attempt completes all subsequent calls to 
WSAConnect on the same socket will fail with the error code WSAEALREADY. 


lf the return error code indicates the connection attempt failed (that is, 
WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the sesiicancn can 
Call wSAConnect again for the same socket. 


Error soda 


WSANOTINITIALISED 


WSAENETDOWN 
WSAEADDRINUSE 


WSAEINTR 
WSAEINPROGRESS 
WSAEALREADY 


WSAEADDRNOTAVAIL 
WSAEAFNOSUPPORT 
WSAECONNREFUSED 
WSAEFAULT 


WSAEINVAL 
_ WSAEISCONN 


WSAENETUNREACH _ 


WSAENOBUFS 


Meaning 

A successful WSAStartup call must occur before using this 
function. 

The network subsystem has failed. 

The local address of the socket is already in use and the socket 
was not marked to allow address reuse with SO_REUSEADDR. 
This error usually occurs during the execution of bind, but could 
be delayed until this function if the bind function operates on a 
partially wildcard address (involving ADDR_ANY) and if a specific 
address needs to be “committed” at the time of this function. 

The (blocking) Windows Socket 1.1 call was canceled through 
WSACancelBlockingCall. 

A blocking Windows Sockets 1.1 call is in progress, or the service 
provider is still processing a callback function. 

A nonblocking connect/WSAConnect call is in progress on the 
specified socket. 

The remote address is not a valid address (such as ADDR_ANY). 
Addresses in the specified family cannot be used with this socket. 
The attempt to connect was rejected. | | 

The name or the namelen parameter is not a valid part of the user 


~ address space, the namelen parameter is too small, the buffer 


length for |pCalleeData, |pDSQOS, and |pGQOS are too small, or 
the buffer length for /pCallerData is too -arge 


The parameter s is a listening socket. 


The socket is already connected Aco -oriented 


sockets only). 
The network cannot be reached from this host at this time. 


: nO eae space is available. The socket cannot be connected. 


- (continued) 
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(continued) 
Error code Meaning 
WSAENOTSOCK The descriptor is not a socket. 
WSAEOPNOTSUPP | The FLOWSPEC structures apered in |IpSQOS ana Pages 


cannot be satisfied. 


WSAEPROTONOSUPPORT _ The IpCallerData argument is not supported by the service 


provider. 
WSAETIMEDOUT Attempt to connect timed out without establishing a connection. 
WSAEWOULDBLOCK The socket is marked as nonblocking and the connection cannot — 


be completed immediately. 


WSAEACCES | Attempt to connect datagram socket to broadcast address failed 


because setsockopt SO_BROADCAST is not enabled. 


Remarks 


The WSAConnect function is used to create a connection to the specified destination, 
and to perform a number of other ancillary operations that occur at connect time. If the 
socket, s, is unbound, unique values are assigned to the local association by the system, 
and the socket is marked as bound. 7 


For connection-oriented sockets (for example, tyoe SOCK_STREAM), an active 
connection is initiated to the foreign host using name (an address in the name space of | 
the socket; for a detailed description, please see bind). When this call completes 
successfully, the socket is ready to send/receive data. If the address parameter of the 
name structure is all zeroes, WSAConnect will return the error WSAEADDRNOTAVAIL. 
Any attempt to reconnect an active connection will fail with the error code 
WSAEISCONN. 


For connection-oriented, nonblocking sockets, it is often not possible to complete the 
connection immediately. In such cases, this function returns the error 
WSAEWOULDBLOCK. However, the operation proceeds. When the success or failure 
outcome becomes known, it may be reported in one of several ways depending on how 
the client registers for notification. If the client uses select, success is reported in the 
writefds set and failure is reported in the exceptfds set. If the client uses _ 
WSAAsyncSelect or WSAEventSelect, the notification is announced with 
FD_CONNECT and the error code associated with the FD CONNECT indicates either 
SUCCESS OF a specific reason for failure. 


Fora connectionless socket (for example, type SOCK _DGRAM), the operation 
performed by WSAConnect is merely to establish a default destination address so that 
the socket can be used on subsequent connection-oriented send and receive operations 
(send, WSASend, recv, and WSARecv). Any datagrams received from an address 
other than the destination address specified will be discarded. If the entire name | 
structure is all zeros (not just the address parameter of the name structure), then the 
socket will be disconnected. Then, the default remote address will be indeterminate, so 
send/WSASend and recv/WSARecv calls will return the error code WSAENOTCONN. 


However, sendto/WSASendTo and recvfrom/WSARecvFrom can still be used. 
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The default destination can be changed by simply calling WSAConnect again, even if 
the socket is already connected. Any datagrams queued for receipt are discarded if | 
name is different from the previous WSAConnect. 


For connectionless sockets, name can indicate any valid address, including a broadcast 
address. However, to connect to a broadcast address, a socket must have setsockopt 
SO_BROADCAST enabled. Otherwise, WSAConnect will fail with the error code 
WSAEACCES. 


On connectionless sockets, exchange of user-to-user data is not possible and the 
corresponding parameters will be silently ignored. 


The application is responsible for allocating any memory space pointed to directly or 
indirectly by any of the parameters it specifies. 


The /pCallerData is a value parameter that contains any user data that is to be sent 
along with the connection request. If joCallerData is NULL, no user data will be passed 
to the peer. The /oCalleeData is a result parameter that will contain any user data 
passed back from the other socket as part of the connection establishment in a 
WSABUF structure. The member /pCalleeData->/en initially contains the length of the 
buffer allocated by the application and pointed to by /pCalleeData->buf. IpCalleeData- 
>len will be set to zero if no user data has been passed back. The /pCalleeData 
information will be valid when the connection operation is complete. For blocking 
sockets, the connection operation completes when the WSAConnect function returns. 
For nonblocking sockets, completion will be after the FD_CONNECT notification has 
occurred. If /pCalleeData is NULL, no user data will be passed back. The exact format of 
the user data is specific to the address family to which the socket belongs. _ | 


At connect time, an application can use the /|pDSQOS parameter to override any previous 
quality of service specification made for the socket through motoct) with the 
SIO_SET_QOS opcode. | 


IpDSQOS specifies the FLOWSPEC structures for socket s, one for each direction, 
followed by any additional provider-specific parameters. If either the associated transport 
provider in general or the specific type of socket in particular cannot honor the quality of 
service request, an error will be returned as indicated in the following. The sending or 
receiving flow specification values will be ignored, respectively, for any unidirectional 
sockets. If no provider-specific parameters are supplied, the buf and /en parameters of 
IpSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value 
for |pDSQOS indicates no application supplied quality of service. 


_ When connected sockets become closed for whatever reason, they should be discarded 
and recreated. It is safest to assume that when things go awry for any reason ona 
connected socket, the application must discard and recreate the needed sockets in order 
to return to a stable point. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
‘Extension Functions, accept, bind, connect, getsockname, getsockopt, select, 


socket, WSAAsyncSelect, WSAEventSelect 


WSACreateEvent 


The Windows Sockets WSACreateEvent function creates a new event object. 


Parameters 
This function has no parameters. 


Return Values 


lf no error occurs, WSACreateEvent returns the handle of the event object. Otherwise, 
the return value is WSA_INVALID_EVENT. To get extended error information, call 
WSAGetLastError. 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur 
| , before using this function. | 

WSAENETDOWN The network subsystem has failed. — 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in 


progress, or the service provider is still 
processing a callback function. 


WSA_NOT_ENOUGH_MEMORY Not enough free memory available to create the 
| event object. 


Remarks 


_ The WSACreateEvent function is used to create an event object created that is manual 


reset with an initial state of nonsignaled. Windows Sockets 2 event objects are system 
objects in Win32 environments. Therefore, if a Win32 application desires auto reset 
events, it can call the native WSACreateEvent Win32 function directly. The scope of an 
event object is limited to the process in which it is created. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSACloseEvent, WSAEnumNetworkEvents, WSAEventSelect, 
WSAGetOverlappedResult, WSARecv, WSARecvFrom, WSAResetEvent, 
WSASend, WSASendTo, WSASetEvent, WSAWaitForMultipleEvents 


WSADuplicateSocket 


The Windows Sockets WSADuplicateSocket function returns a 
WSAPROTOCOL_INFO structure that can be used to create a new socket descriptor for 
a shared socket. The WSADuplicateSocket function cannot be used on a QOS-enabled 
socket. | 


‘Parameters 


S | | 
[in] Descriptor identifying the local socket. 


dwProcessld — | 
[in] Process identifier of the target process in which the duplicated socket will be used. 


lpProtocolinfo 
[out] Pointer to a buffer, allocated by the client, that is large enough to contain a 
WSAPROTOCOL_INFO structure. The service provider copies the protocol 
_ information structure contents to this buffer. 


Return Values 


If no error occurs, WSADuplicateSocket returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
WSAGetLastError. 
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Errorcode | | Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. | 
WSAENETDOWN © The network subsystem has failed. 
WSAEINVAL Indicates that one of the specified parameters was 
invalid. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
| ae or the service provider is still processing a callback 
function. 
WSAEMFILE No more socket descriptors are available. 
WSAENOBUFS No buffer space is available. The socket cannot be 
created. 
WSAENOTSOCK The descriptor is not a socket. 
WSAEFAULT The /pProtocolinfo argument is not a valid part of the 


user address space. 


~ Remarks 


The WSADuplicateSocket function is used to enable socket sharing between 
processes. A source process calls WSADuplicateSocket to obtain a special 
WSAPROTOCOL_INFO structure. It uses some interprocess communications (IPC) 
mechanism to pass the contents of this structure to a target process, which in turn uses 
it in a call to WSASocket to obtain a descriptor for the duplicated socket. The special 
WSAPROTOCOL_INFO structure can only be used once by the target process. 


sockets can be shared among threads in a given process without using the 
WSADuplicateSocket function because a socket descriptor is valid in all threads of a 
process 


One possible scenario for establishing and handing off a shared socket is illustrated in 
the following table. 


Source process | IPC Destination process 
1) WSASocket, WSAConnect | 
2) Request target process identifier = 


3) Receive process identifier request 
and respond © | 

4) Receive process identifier = | 
5) Call WSADuplicateSocket to get 

a special WSAPROTOCOL_INFO 
structure 
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Source process IPC Destination process 


6) Send WSAPROTOCOL_INFO 
structure to target 


= 7) Receive WSAPROTOCOL_INFO 
structure 


8) Call WSASocket to create shared 
socket descriptor. 


10) closesocket 9) Use shared socket for data exchange - | 


The descriptors that reference a shared socket can be used independently for I/O. 
However, the Windows Sockets interface does not implement any type of access control, 
so it is up to the processes involved to coordinate their operations on a shared socket. 
Shared sockets are typically used to having one process that is responsible for creating 
sockets and establishing connections, and other processes that are responsible for 
information exchange. 


All of the state information associated with a socket is held in common across all the 
descriptors because the socket descriptors are duplicated and not the actual socket. For 
example, a setsockopt operation performed using one descriptor is subsequently visible 
using a getsockopt from any or all descriptors. A process can call closesocket on a 
‘duplicated socket and the descriptor will become deallocated. The underlying socket, 
however, will remain open until closesocket is called by the last remaining descriptor. — 


Notification on shared sockets is subject to the usual constraints of WSAAsyncSelect 
and WSAEventSelect. Issuing either of these calls using any of the shared descriptors 
cancels any previous event registration for the socket, regardless of which descriptor 
was used to make that registration. Thus, a shared socket cannot deliver FD_READ 
events to process A and FD_WRITE events to process B. For situations when such tight 
coordination is required, developers would be advised to use threads instead of separate 
processes. | 


Note The WSADuplicateSocket function cannot be used on a QOS-enabled socket. 
Attempting to do so will result in the return of a WSAEINVAL error. 


Version: Requires Windows Sockets 2.0. 

Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. 

Unicode: Implemented as Unicode and ANSI versions on all platforms. 


Windows Sockets Programming Considerations Overview, Microsoft Windows: “Specific 
Extension Functions, WSASocket 
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WSAEnumNameSpaceProviders 


The Windows Sockets WSAEnumNameSpaceProviders function retrieves information 
about available name spaces. 


Parameters 


lodwBufferLength 
[in/out] On input, the number of bytes contained in the buffer pointed to by 
lonspBuffer. On output (if the function fails, and the error is WSAEFAULT), the 
minimum number of bytes to pass for the /onspBuffer to retrieve all the requested 
information. The passed-in buffer must be sufficient to hold all of the name space 
information. 


_ IpnspBuffer 
[out] Buffer that is filled with WSANAMESPACE_INFO structures. The returned 
structures are located consecutively at the head of the buffer. Variable sized 
information referenced by pointers in the structures point to locations within the buffer 
located between the end of the fixed sized structures and the end of the buffer. The 
number of structures filled in is the return value of WGAEnumNameSpaceProviders. 


Return Values 


The WSAEnumNameSpaceProviders function returns the number of 
WSANAMESPACE_INFO structures copied into JonspBuffer. Otherwise, the value 
SOCKET_ERROR is returned, and a specie error number can be retrieved by calling 


WSAGetLastError. 
Error code Meaning 
WSAEFAULT The buffer length was too small to receive all the relevant 


WSANAMESPACE_INFO structures and associated information. 
Passes in a buffer at least as large as the value returned in 
lpdwBufferLength. 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The application must first 
call WSAStartup before calling any Windows Sockets functions. 
WSA NOT ENOUGH There was insufficient memory to perform the operation. 
MEMORY | 
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Version: Requires Windows Sockets 2.0. 

Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. 

Unicode: Implemented as Unicode and ANSI versions on all platforms. 


WSAEnumNetworkEvents 


The Windows Sockets WSAEnumNetworkE vents function discovers occurrences of 
network events for the indicated socket, clear internal network event records, and reset 
event objects (optional). 


Parameters 
Ss : 
[in] Descriptor identifying the socket. 
hEventObject | : 
_ [in] Optional handle identifying an associated event object to be reset. 


IpNetworkEvents fms 7 Se 
[out] Pointer to a WSANETWORKEVENTS siructure that is filled with a record of © 
network events that occurred and any associated error codes. 


Return Values 


The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 


WSAGetLastError. 

Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using 

this function. | 

WSAENETDOWN _ The network subsystem has failed. 

WSAEINVAL Indicates that one of the specified parameters was invalid. 

WSAEINPROGRESS A blocking Windows Sockets 1.4 call is in progress, or the 
i service provider is still processing a callback function. 

WSAENOTSOCK The descriptor is not a socket. | 

WSAEFAULT The /pNetworkEvents argument is not a valid part of the 


user address space. 
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Remarks 


The WSAEnumNetworkEvents function is used to discover which network events have 
occurred for the indicated socket since the last invocation of this function. It is intended 
for use in conjunction with WSAEventSelect, which associates an event object with one 
or more network events. The recording of network events commences when 
WSAEventSelect is called with a nonzero /NetworkEvents parameter and remains in 
effect until another call is made to WSAEventSelect with the /NetworkEvents parameter 
set to zero, or until a call is made to WSAAsyncSelect. — | 


WSAEnumNetworkEvents only reports network activity and errors nominated through 
WSAEventSelect. See the descriptions of select and iat aca to find out how 
those functions report network activity and errors. 


The socket’s internal record of network events is copied to the structure referenced by 
IpNetworkEvents, after which the internal network events record is cleared. If the 
hEventObject parameter is not NULL, the indicated event object is also reset. The 
Windows Sockets provider guarantees that the operations of copying the network event 
record, clearing it and resetting any associated event object are automatic, such that the 
next occurrence of a nominated network event will cause the event object to become set. 
In the case of this function returning SOCKET_ERROR, the associated event object is 
not reset and the record of network events is not cleared. 


The /NetworkEvents member of the WSANETWORKEVENTS structure indicates which 
of the FD_XXX network events have occurred. The /ErrorCode array is used to contain 
any associated error codes with the array index corresponding to the position of event 
bits in INetworkEvents. Identifiers such as FD_READ_BIT and FD_WRITE_BIT can be 
used to index the /ErrorCode array. Note that only those elements of the /ErrorCode 
array are set that correspond to the bits set in /NetworkEvents parameter. Other 
parameters are not modified (this is important for backward compatibility with the 
applications that are not aware of new FD_ROUTING_INTERFACE_CHANGE and 
FD_ADDRESS_LIST_CHANGE events). 


The following error codes can be returned along with the corresponding network event. 


Event: FD_ CONNECT 


Errorcode _ oe Meaning 
WSAEAFNOSUPPORT _ Addresses in the specified family cannot be used 
| with this socket. 7 
WSAECONNREFUSED 7 The attempt to connect was forcefully rejected. 
WSAENETUNREACH _ The network cannot be reached from this host at this 
| | time. 
WSAENOBUFS No buffer space is available. ug socket ¢ cannot be 
connected. 
~ WSAETIMEDOUT Attempt to connect timed out without establishing a 


connection 


Event: FD CLOSE 


Error code 


WSAENETDOWN 
WSAECONNRESET 
WSAECONNABORTED 


Event: FD_READ 
Event: FD_WRITE 
Event: FD_OOB 
Event: FD_ACCEPT 
Event: FD_QOS 


Event: FD_ GROUP _QOS 
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Meaning 


The network subsystem has failed. 


The connection was reset by the remote side. 


The connection was terminated due to a time-out or 
other failure. 


Event: FD_ADDRESS_LIST_CHANGE 


Error code 


WSAENETDOWN 


Meaning 


The network subsystem has failed. 


Event: FD_ROUTING_INTERFACE_CHANGE 


_ Error code 


| WSAENETUNREACH 
WSAENETDOWN 


Meaning 


The specified destination is no longer reachable. 
The network subsystem has failed. 


Version: Requires Windows Sockets 2.0. 


Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


a 


Windows Sockets Programming Considerations Overview, Microsoft Windows: -Specific 
Extension Functions, WSAEventSelect 


‘WSAEnumProtocols 


The Windows Sockets WSAEnumProtocols function retrieves information about 


available transport protocols. 
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Parameters 


IpiProtocols 
[in] Null-terminated array of iProtocol values. This parameter is optional; if joiProtocols 
is NULL, information on all available protocols is returned. Otherwise, information is 
retrieved only for those protocols listed in the array. 


loProtocolBuffer 
[out] Buffer that is filled with WSAPROTOCOL_INFO structures. 


lodwBufferLength 
[in/out] On input, the count of bytes in the /oProtoco/Buffer buffer passed to 
WSAEnumProtocols. On output, the minimum buffer size that can be passed to 
WSAEnumProtocols to retrieve all the requested information. This routine has no 
ability to enumerate over multiple calls; the passed-in buffer must be large enough to 
hold all entries in order for the routine to succeed. This reduces the complexity of the 
API and should not pose a problem because the number of protocols loaded on a 
machine is typically small. 


Return Values 


If no error occurs, WSAEnumProtocols returns the number of protocols to be reported. 
Otherwise, a value of SOCKET_ERROR is returned and a specific error code can be 
retrieved by calling WSAGetLastError. | 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress. 

WSAEINVAL Indicates that one of the specified parameters was 
invalid. 

WSAENOBUFS The buffer length was too small to receive all the 


relevant WSAPROTOCOL_INFO structures and 
associated information. Pass in a buffer at least as 
large as the value returned in /odwBufferLength. 


WSAEFAULT One or more of the /piProtocols, |pProtocolBuffer, or 
lpdwBufferLength arguments are not a valid part of 
the user address space. 
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Remarks 


The WSAEnumProtocols function is used to discover information about the collection of 
transport protocols and protocol chains installed on the local machine. Since layered 
protocols are only usable by applications when installed in protocol chains, information 
on layered protocols is not included in /pProtoco/Buffer. The |piProtocols parameter can 
be used as a filter to constrain the amount of information provided. Often, /piProtocols 
will be supplied as a NULL pointer that will cause the function to return information on all 
available transport protocols and protocol chains. 


A WSAPROTOCOL_INFO structure is provided in the buffer pointed to by 
lpProtocolBuffer for each requested protocol. If the supplied buffer is not large enough 
(as indicated by the input value of /odwBufferLength ), the value pointed to by 
lpdwBufferLength will be updated to indicate the required buffer size. The application 
should then obtain a large enough buffer and call this WSAEnumProtocols again. 


The order in which the WSAPROTOCOL_INFO structures appear in the buffer coincides 
with the order in which the protocol entries were registered by the service provider using 
the Ws2_32.dll, or with any subsequent reordering that occurred through the Windows 
Sockets applet or DLL supplied for establishing default TCP/IP providers. — 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
_ Library: Use Ws2_32.lib. - 
Unicode: Implemented as Unicode and ANSI versions on all platiorms. 
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WSAEventSelect 


The Windows Sockets WSAEventSelect function specifies an event object to be 
associated with the supplied set of FD_XXX network events. 


Parameters 
S 


[in] Descriptor identifying the socket. 
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hEventObject | 
[in] Handle identifying the event object to be associated with the supplied set of 
FD_XXX network events. 


INetworkEvents | 
[in] Bitmask that specifies the combination of FD_XXX network events in which the 
application has interest. , | 


Return Values 


The return value is zero if the application’s specification of the network events and the 
associated event object was successful. Otherwise, the value SOCKET_ERROR is 
returned, and a specific error number can be retrieved by calling WSAGetLastError. 


As in the case of the select and WSAAsyncSelect functions, WSAEventSelect will 
frequently be used to determine when a data transfer operation (send or recv) can be 
issued with the expectation of immediate success. Nevertheless, a robust application 
must be prepared for the possibility that the event object is set and it issues a Windows 
Sockets call that returns WSAEWOULDBLOCK immediately. For ill the following 
sequence of operations is possible: 


e Data arrives on socket s; Windows Sockets sets the WSAEventSelect event object. 


e The application does some other processing. 


e While processing, the application issues an ioctlsocket(s, FIONREAD.. ) and notices 
that there is data ready to be read. 


e The application issues a recv(s,...) to read the data. 


e The application eventually waits on the event object specified in WSAEventSelect, 
which returns immediately indicating that data is ready to read. 


e The application issues recv(s,...), which fails with the error WSAEWOULDBLOCK. 


Having successfully recorded the occurrence of the network event (by setting the 
corresponding bit in the internal network event record) and signaled the associated 
event object, no further actions are taken for that network event until the application 
makes the function call that implicitly reenables the setting of that network event and 
signaling of the associated event object. | 


Network event -Re-enabling function 

FD_READ __reev, recvfrom, WSARecv, or WSARecvFrom. 
FD_WRITE | _ send, sendto, WSASend, or WSASendTo. 
_FD_LOOB | ; -recv, recvfrom, WSARecv, or WSARecvFrom. 
~ FD_ACCEPT — accept or WSAAccept unless the error code returned is 


WSATRY_AGAIN indicating that the condition function 
returned CF_DEFER. 


FD_CONNECT None. 
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Network event Re-enabling function 

FD CLOSE None. 

FD_QOS WSAloctl with command SIO_GET_QOS. 
FD _GROUP_QOS Reserved. 

FD ROUTING. WSAloctl with command 
INTERFACE_CHANGE SIO_ROUTING_INTERFACE_CHANGE. 
FD ADDRESS _ WSAloctl with command 7 

LIST CHANGE SIO_ADDRESS_LIST_CHANGE. 


Any call to the reenabling routine, even one that fails, results in reenabling of recording 
and signaling for the relevant network event and event object. 


-For FD_READ, FD_OOB, and FD_ACCEPT network events, network event recording - 
and event object signaling are level-triggered. This means that if the reenabling routine 
is called and the relevant network condition is still valid after the call, the network event 
is recorded and the associated event object is set. This allows an application to be 
event-driven and not be concerned with the amount of data that arrives at any one time. 
Consider the following sequence: | 


— 1. Transport provider receives 100 bytes of data on socket Ss and c causes Ws2_32. dil to 
record the FD_READ network event and set the associated event object. 
2. The application i issues recv( S, buffptr, 50, 0) to read 50 bytes. 


3. The transport provider causes Ws2_32.dll to record the FD_READ network event and 
sets the associated event object again since there is still data to be read. : 


| With these semantics, an application need not read all available data in response to an 
FD_READ network event—a A sifigie recv in eer oes to each FD_READ network event 


_ is appropriate. 


The FD_QOS event is considered edge triggered. A message will be posted exactly 
once when a quality of service change occurs. Further messages will not be forthcoming 
until either the provider detects a further change in quality of service or the application 
renegotiates the quality of service for the socket. 


The FD_ROUTING_INTERFACE_CHANGE and FD _ADDRESS LIST_ CHANGE events. 
are considered edge triggered as well. A message will be posted exactly once when a 
change occurs after the application has requested the notification by issuing WSAloctl 
with SIO_LROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE 
correspondingly. Other messages will not be forthcoming until the application reissues 
the IOCTL and another change is detected since the IOCTL has been issued. 


If a network event has already happened when the application calls WSAEventSelect or | 
when the reenabling function is called, then a network event is recorded and the 
associated event object | is set as appropriate. For example, consider the etolon ne 
sequence: , : 
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1. An application calls listen. 
2. Aconnect request is received but not yet accepted. 


3. The application calls WSAEventSelect specifying that it is interested in the 
FD_ACCEPT network event for the socket. Due to the persistence of network events, 
Windows Sockets records the FD_ACCEPT network event and sets the associated 
event object immediately. 


The FD_WRITE network event is handled slightly differently. An FD_WRITE network 
event is recorded when a socket is first connected with connect/WSAConnect or 
accepted with accept/WSAAccept, and then after a send fails with 
WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application 
can assume that sends are possible starting from the first FD_WRITE network event 
setting and lasting until a send returns WSAEWOULDBLOCK. After such a failure the 
application will find out that sends are again possible when an FD_WRITE network event 
is recorded and the associated event object is set. 


The FD_OOB network event is used only when a socket is configured to receive OOB 
data separately. If the socket is configured to receive OOB data inline, the OOB 
(expedited) data is treated as normal data and the application should register an interest 
in, and will get FD_READ network event, not FD_OOB network event. An application 
can set or inspect the way in which OOB data is to be handled by using setsockopt or 
getsockopt for the SO_OOBINLINE option. 


The error code in an FD_CLOSE network event indicates whether the socket close was 
graceful or abortive. If the error code is zero, then the close was graceful; if the error 
code is WSAECONNRESET, then the socket’s virtual circuit was reset. This only applies 
to connection-oriented sockets such as SOCK_STREAM. 


The FD_CLOSE network event is recorded when a close indication is received for the 
virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE 
is recorded when the connection goes into the TIME WAIT or CLOSE WAIT states. This 
results from the remote end performing a shutdown on the send side or a closesocket. 
FD_CLOSE being posted after all data is read from a socket. An application should 
check for remaining data upon receipt of FD_CLOSE to avoid any possibility of losing 


data. 


Please note Windows Sockets will record only an FD_CLOSE network event to indicate 
closure of a virtual circuit. It will not record an FD_READ network event to indicate this 
condition. 


The FD_QOS network event is recorded when any parameter in the flow specification 
associated with socket s. Applications should use WSAloctl with command 


— SIO_GET_QOS to get the current Qos for socket Ss. 
~ The FD_ROUTING_INTERFACE_CHANGE network event is recorded when the local 


interface that should be used to reach the destination specified in WSAloctl with 
SIO_ROUTING_INTERFACE_CHANGE changes after such IOCTL has been issued. 
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The FD_ADDRESS_LIST_CHANGE network event is recorded when the list of 
addresses of protocol family for the socket to which the application can bind changes 
after WSAloctl with SIO_ADDRESS_LIST_ CHANGE has been issued. 


Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before using this 
function. 
WSAENETDOWN The network subsystem has failed. 
WSAEINVAL Indicates that one of the specified parameters was invalid, 
a | or the specified socket is in an invalid state. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
: service provider is still processing a callback function. 
WSAENOTSOCK The descriptor is nota socket. 
Remarks 


The WSAEventSelect function is used to specify an event object, hEventObject to be 
associated with the selected FD_XXX network events, /NetworkEvents. The socket for 
which an event object is specified is identified by the s paramelrl: The event object is set 
when any of the nominated network events Occur. 


The WSAEventSelect function operates very similarly to WSAAsyncSelect, the 
difference being the actions taken when a nominated network event occurs. The 
WSAAsyncSelect function causes an application-specified Windows message to be 
posted. The WSAEventSelect sets the associated event object and records the 
occurrence of this event in an internal network event record. An application can use 
WSAWaitForMultipleEvents to wait or poll on the event object, and use | 
WSAEnumNetworkEvents to retrieve the contents of the internal network event record 
and thus determine which of the nominated network events have occurred. 


~WSAEventSelect is the only function that causes network activity and errors to be 

recorded and retrievable through WSAEnumNetworkEvents. See the descriptions of 

select and WSAAsyncSelect to find out how those functions report network actly and 
errors. 


The WSAEventSelect function automatically sets socket s to nonpiseking mode, 
regardless of the value of /NetworkEvents. See ioctlsocket/WSAloct! about how to set 
the socket back to blocking mode. | 


The /NetworkEvents parameter is constructed by using the bitwise OR operator with any | 
“ of the values specified in the following table. 


Value | Meaning | 
FD_READ 7 Wants to receive notification of readiness for reading. 


FD_WRITE Wants to receive notification of readiness for writing. 
| i ~ (continued) 
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(continued) 
Value 


FD_OOB 
FD_ACCEPT 
FD_CONNECT 


FD_CLOSE 
FD_QOS 
FD_GROUP_QOS 


FD_ROUTING_ | 
INTERFACE_CHANGE 


FD_ADDRESS_ 
LIST_CHANGE 


Meaning 


Wants to receive notification of the arrival of OOB data. 
Wants to receive notification of incoming connections. 


Wants to receive notification of completed connection or 
multipoint join operation. 


Wants to receive notification of socket closure. _ 
Wants to receive notification of socket (QOS changes. 
Reserved. 


Wants to receive notification of routing interface changes 
for the specified destination. 


Wants to receive notification of local address list changes 
for the address family of the socket. 


Issuing a WSAEventSelect for a socket cancels any previous WSAAsyncSelect or 
WSAEventSelect for the same socket and clears the internal network event record. For 
example, to associate an event object with both reading and writing network events, the 


application must call WSAEventSelect with both FD_READ and FD_WRITE, as follows: 


It is not possible to specify different event objects for different network events. The 


following code will not work; the second call will cancel the effects of the first, and only 
the FD_WRITE network event will be associated with hEventObjeci2: 


To cancel the association and selection of network events on a socket, /NetworkEvents 
should be set to zero, in which case the hEventObject parameter will be ignored. 


Closing a socket with closesocket also cancels the association and selection of network 
events specified in WSAEventSelect for the socket. The application, however, still must 
call WSACloseEvent to explicitly close the event object and free any resources. 


The socket created when the accept function is called has the same properties as the 
listening socket used to accept it. Any WSAEventSelect association and network events 
selection set for the listening socket apply to the accepted socket. For example, if a 
listening socket has WSAEventSelect association of hEventOject with FD_ACCEPT, 
FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also 
have FD_ACCEPT, FD_READ, and FD_WRITE network events associated with the 
same hEventObject. \f a different hEventObject or network events are desired, the 
application should call WSAEventSelect, passing the accepted socket and the desired 


~new information. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific . 
Extension Functions, WSAAsyncSelect, WSACloseE vent, WSACreateEvent, 
WSAEnumNetworkEvents, WSAWaitForMultipleEvents 


WSAGetLastError 


The Windows Sockets WSAGetLastError f function gets the error Status for the last 
operation that failed. 


Parameters 
This function has no parameters. 


Return Values 


The return value indicates the error code for this thread’s ast Windows Sockets 
operation that failed. 


Remarks 


The WSAGetLastError function returns the last network error that occurred. When a 
particular Windows Sockets function indicates that an error has occurred, this function 
should be called to retrieve the appropriate error code. This error code can be different 
from the error code obtained from getsockopt SO_ERROR, which is socket-specific 
since WSAGetLastError is for all thread-specific sockets. | 


A successful function call, or a call to WSAGetLastError, does not reset the error code. 
To reset the error code, use the WSASetLastError function call with iError set to zero. A 
getsockopt SO_ERROR also resets the error code to zero. 


- The WSAGetLastError function should not be used to check for an error vale on 
receipt of an asynchronous message. In this case, the error value is passed in the 
/Param parameter of the message, and this can differ from the a returned by 
Wane ester, 
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Ss 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, getsockopt, WSASetLastError 


WSAGetOverlappedResult 


The Windows Sockets WSAGetOverlappedResult function returns the results of an 
overlapped operation on the specified socket. 


Parameters 
S 


[in] Descriptor identifying the socket. This is the same socket that was specified when 
the overlapped operation was started by a call to WSARecv, WSARecvFrom, 
WSASend, WSASendTo, or WSAloctl. 


IDOverlapped 
in] Pointer toa WSAOVERLAPPED structure that was specified when the 
overlapped operation was started. 


pcb Transfer 


out] Pointer to a 32-bit variable that receives the number of bytes that were actually 
transferred by a send or receive operation, or by WSAloctl. 


fWait 
[in] Flag that specifies whether the function should wait for the pending overlapped 
operation to complete. If TRUE, the function does not return until the operation has 
been completed. If FALSE and the operation is still pending, the function returns 
FALSE and the WSAGetLastError function returns WSA_IO_INCOMPLETE. The 
fWait parameter may be set to TRUE only if the overlapped operation selected the 
event-based completion notification. | 
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lodwFlags 
[out] Pointer to a 32-bit variable that will receive one or more flags that supplement 
the completion status. If the overlapped operation was initiated through WSARecv or 
WSARecvF ron, this parameter will contain the results value for joFlags parameter. 


Return Values 

lf WSAGetOverlappedResult succeeds, the return value is TRUE. This means that the | 
overlapped operation has completed successfully and that the value pointed to by 
IpcbTransfer has been updated. If WSAGetOverlappedResult returns FALSE, this 
means that either the overlapped operation has not completed, the overlapped operation 
completed but with errors, or the overlapped operation’s completion status could not be 
determined due to errors in one or more parameters to WSAGetOverlappedResult. On 
failure, the value pointed to by /ocbTransfer will not be updated. Use WSAGetLastError 
to determine the cause of the failure (either of Won Gato venappednesult or of the 
associated overlapped operation): 


Error code | Meaning 
~WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 
WSAENETDOWN The network subsystem has failed. 
WSAENOTSOCK The descriptor is not a socket. 
WSA_INVALIDLHANDLE | The hEvent parameter of the 


WSAOVERLAPPED structure does not contain 
a valid event object handle. 


~WSA_INVALID_PARAMETER _ One of the parameters is unacceptable. 
WSA_IO_INCOMPLETE The fWait parameter is FALSE and the I/O 
| operation has not yet completed. 
WSAEFAULT | One or more of the /pOverlapped, Ipcb Transfer, 


or |pdwFlags arguments are not a valid part of 
the user address space. 


Remarks | ; . 
The WSAGetOverlappedResult function reports the results of the last overlapped 
operation for the specified socket. The WSAOverlappedResult function is passed the 
socket descriptor and the WSAOVERLAPPED structure that was specified when the 
overlapped function was called. A pending operation is indicated when the function that 
started the operation returns FALSE and the WSAGetLastError function returns 
WSA_IO_PENDING. When an I/O operation such as WSARecv is pending, the function 
that started the operation resets the hEvent member of the WSAOVERLAPPED | 
structure to the nonsignaled state. Then, when the pending pees has completed, the 
‘system sets the event opject to the signaled state. 
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If the fWait parameter is TRUE, WSAGetOverlappedResult determines whether the 
pending operation has been completed by waiting for the event object to be in the 
signaled state. A client may set the fWait parameter to TRUE, but only if it selected 
event-based completion notification when the I/O operation was requested. If another 
form of notification was selected, the usage of the hEvent parameter of the 
WSAOVERLAPPED structure is different, and setting fWa/t to TRUE causes 


unpredictable results. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSAAccept, WSAConnect, WSACreateEvent, WSAloctil, 
WSARecv, WSARecvFrom, WSASend, WSASendTo, WSAWaitForMultipleEvents 


WSAGetQOSByName 


The Windows Sockets WSAGetQOSByName function initializes a QOS structure based 
on a named template, or it supplies a buffer to retrieve an enumeration of the available 


template names. 


arameters 
S 
[in] Descriptor identifying a socket. 


IpDQOSName 
in out] Pointer to a specific quality of service template. 


IpQOS 
[out] Pointer to the QOS structure to be filled. 


Return Values 


lf WSAGetQOSByName succeeds, the return value is TRUE. If the function fails, the 
return value is FALSE. To get extended error information, call WSAGetLastError. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using 
this function. 

WSAENETDOWN The network subsystem has failed. 

WSAENOTSOCK The descriptor is not a socket. 

WSAEFAULT The /pQOSName or |pQOS parameter are not a valid 


part of the user address space, or the buffer length for 
IpDQOS is too small. 


WSAENVAL The specified QOS template name is invalid. 


Remarks 

The WSAGetQOSByName function is used by applications to initialize a QOS structure 
to a set of known values appropriate for a particular service class or media type. These 
values are stored in a template that is referenced by a well-known name. The client may 
retrieve these values by setting the buf parameter of the WSABUF structure indicated by 
lpDQOSName, which points to a string of nonzero length specifying a template name. In 
this case, the usage of JODQOSName is IN only, and results are returned through /oQOS. 


Alternatively, the client may use this function to retrieve an enumeration of available 
template names. The client may do this by setting the buf parameter of the WSABUF 
indicated by |pQOSName to a zero-length null-terminated string. In this case the buffer 
indicated by buf is overwritten with a sequence of as many available, null-terminated 

~ template names up to the number of bytes available in buf as indicated by the len 
parameter of the WSABUF indicated by |pQOSName. The list of names itself is 
terminated by a zero-length name. When the WSAGetQOSByName function is used to 
retrieve template names, the /oQOS parameter is ignored. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows- -Specific 
Extension Functions, getsockopt, WSAAccept, WSAConnect 
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WSAGetServiceClassinfo 


The Windows Sockets WSAGetServiceClassiInfo function retrieves all of the class 
information (schema) pertaining to a specified service class from a specified name space 
provider. 


Parameters 


loProviderld 
[in] Pointer to a GUID that identifies a specific name space provider. 


IpServiceClassld 
[in] Pointer to a GUID identifying the service class. 


lodwBufferLength 
[in/out] On input, the number of bytes contained in the buffer pointed to by 
lpServiceClassInfos. On output, if the function fails and the error is WSAEFAULT, 
then it contains the minimum number of bytes to pass for the /pServiceClassInfo to 
retrieve the record. 


lpServiceClassinfo | 
[out] Pointer to the service class information from the indicated name space provider 
for the specified service class. 


Return Values 


The return value is zero if the WSAGetServiceClassInfo was successful. Otherwise, the 
value SOCKET_ERROR is returned, and a specific error number can be retrieved by 
calling WSAGetLastError. 


Error code Meaning 
WSAEACCESS The calling routine does not have sufficient 
privileges to access the information. 
WSAEFAULT The buffer referenced by |pServiceClassinfo is 
too small. Pass in a larger buffer. 
WSAEINVAL | The specified service class identifier or name 
| space provider identifier is invalid. 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Sockets functions. 
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Error code Meaning 

WSATYPE NOT FOUND The specified class was not found. 

WSA NOT ENOUGH MEMORY | There was insufficient memory to perform the 
operation. 

Remarks 


The WSAGetServiceClassinfo function retrieves service class information but the 
service class information retrieved from a particular name space provider might not be 
the complete set of class information that was supplied when the service class was 
installed. Individual name space providers are only required to retain service class 


information that is applicable to the name spaces that they support. See the section 
Service Class Data Structures for more information. 


Version: Requires Windows Sockets 2.0. 

Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. | 
Unicode: Implemented as Unicode and ANSI versions on all platforms. 


WSAGetServiceClassNameByClassld 


The Windows Sockets WSAGetServiceClassNameByClassid function returns the 
name of the service associated with the given type. This name is the generic service 
name, like FTP or SNA, and not the name of a specific instance of that service. 


Parameters 
IpServiceClassld 
[in] Pointer to the GUID for the service class. 


loszServiceClassName 
[out] Pointer to the service name. 


lodwBufferLength ae: 


[in/out] On input, the length of the buffer returned by /pszServiceClassName. On 
output, the length of the service name copied into lpszServiceClassName. 


294 Volume 1 Winsock and QOS 


Return Values 


The WSAGetServiceClassNameByClassld function returns a value of zero if 
successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error 
number can be retrieved by calling WSAGetLastError. 


Error code | Meaning 7 | 


WSAEFAULT The specified buffer referenced by | 
lpszServiceClassName is too small. Pass ina 
larger buffer. 


WSA_INVALID_PARAMETER The /IpServiceClass/d parameter specified is 
invalid. 
WSANOTINITIALIZED The Ws2_ 32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Sockets functions. 


WSA NOT ENOUGH MEMORY There was insufficient memory to perform the 
operation. | 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


WSAHtonI 


The Windows Sockets WSAHtonI function converts a u_long from host byte order to 
network byte order. 


Parameters 
S 
[in] Descriptor identifying a socket. 
hostiong 
[in] 32-bit number in host byte order. 
Ipnetiong — oe | 
[out] Pointer to a 32-bit number in network byte order. 
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Return Values 


If no error occurs, WSAHtonI returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
function. 

WSAENETDOWN The network subsystem has failed. 

WSAENOTSOCK The descriptor is not a socket. 

WSAEFAULT The /pnetiong parameter is not completely eeniaines ina 


valid part of the user address space. 


Remarks | 

The WSAHtonl function takes a 32-bit number in host byte order and returns a 32-bit 
number pointed to by the /pnetiong parameter in the network byte order associated with 
socket s. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
_ Library: Use Ws2_32.lib. 


Windows sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, htonl, htons, ntohl, ntohs, WSANtoh!I, WSAHtons, WSANtohs 


-WSAHtons 


The Windows Sockets WSAHtons function converts a u_short from host byte order to 
network byte order. 


Parameters 
[in] Descriptor identifying a socket. 
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hostshort 
[in] 16-bit number in host byte order. 


Ipnetshort | 
[out] Pointer to a 16-bit number in network byte order. 


Return Values 


If no error occurs, WSAHtons returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur before using 
| this function. 
WSAENETDOWN The network subsystem has failed. 
WSAENOTSOCK The descriptor is not a socket. 
WSAEFAULT The /onetshort parameter is not completely contained ina 


valid part of the user address space. 


Remarks | 

The WSAHtons function takes a 16-bit number in host byte order and returns a 16-bit 
number pointed to by the /onetshort parameter in the network byte order associated with 
socket s. 


a: 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, htonl, htons, ntohl, ntohs, WSAHtonI, WSANtohI, WSANtohs 


WSAlnstallServiceClass — 


The Windows Sockets WSAlnstallServiceClass function registers a service class 
schema within a name space. This schema includes the class name, class identifier, and 
any name space-specific information that is common to all instances of the service, such 
as the SAP identifier or object identifier. | 
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Parameters 

IpServiceClassinfo 
[in] Service class to name space specific-type mapping information. Multiple 
mappings can be handled at one time. _ 
See the section Service Class Data Structures for a description of pertinent data 
structures. 


Return Values 


The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 


WSAGetLastError. 

Error code Meaning 

WSAEACCES The calling function does not have sufficient 
privileges to install the service. 

WSAEALREADY Service class information has already been 
registered for this service class identifier. To 
modify service class information, first use 
WSARemoveServiceClass, and then reinstall 
with updated class information data. 

WSAEINVAL The service class information was invalid or 

| improperly structured. 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
Calling any Windows Sockets functions. 


WSA NOT ENOUGH MEMORY There was insufficient memory to perform the 
operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 

Unicode: Implemented as Unicode and ANSI versions on all platforms. 


- WSAloct 


The Windows Sockets WSAloctl function controls the mode of a socket, 


(continued) 


298 


Volume 1 Winsock and QOS | 


(continued) 


Parameters 
S 
[in] Descriptor identifying a socket. 


dwloControlCode 
[in] Control code of operation to perform. 


lpvinBuffer 
[in] Pointer to the input buffer. 


cbinBuffer 
[in] Size of the input buffer. 


lpvOutBuffer 
[out] Pointer to the output buffer. 


cbOutBuffer | 
[in] Size of the output buffer. 


lpocbBytesReturned 
[out] Pointer to actual number of bytes of output. 


lpOverlapped 
in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets). 


loCompletionRoutine 
in] Pointer to the completion routine called when the operation has been completed 
(ignored for nonoverlapped sockets). 


Return Values | 


Upon successful completion, the WSAloctl returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
WSAGetLastError. 


Error code Meaning 
WSAENETDOWN The network subsystem has failed. 
WSAEFAULT The /pvinBuffer, |pvOutBuffer lpcbBytesReturned, 


IpOverlapped, or |pCompletionRoutine argument is not 
totally contained in a valid part of the user address space, 
or the cb/inBuffer or cbOutBuffer argument is too small. 
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Error code Meaning 


WSAEINVAL dwloControlCode is not a valid command, or a supplied 
input parameter is not acceptable, or the command is not 
applicable to the type of socket supplied. 


WSAEINPROGRESS The function is invoked when a callback is in progress. 
WSAENOTSOCK The descriptor s is not a socket. 
WSAEOPNOTSUPP The specified ioctl command cannot be realized. 


(For example, the FLOWSPEC structures specified in 
SIO_SET_QOS cannot be satisfied.) 


~WSA_IO_PENDING _ An overlapped operation was successfully initiated and 
completion will be indicated at a later time. 


WSAEWOULDBLOCK The socket is marked as nonblocking and the requested 
operation would block. | 


Remarks 


The WSAloctI function is used to set or retrieve operating parameters associated with 
the socket, the transport protocol, or the communications subsystem. | 


If both jpOverlapped and |pCompletionRoutine are NULL, the socket in this function will 
~ be treated as a nonoverlapped socket. For a nonoverlapped socket, /oOverlapped and 
lpCompletionRoutine parameters are ignored, which cause the function to behave like 
the standard ioctlsocket function except that WSAloctl can block if socket s is in 
blocking mode. If socket sis in nonblocking mode, this function can return 
WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In 
this case, the application may change the socket to blocking mode and reissue the 
request or wait for the corresponding network event (such as 
FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case 
of SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE) using a 
Windows message-based (using WSAAsyncSelect) or event (using WS EVeneleeh): 
based notification mechanism. 


For overlapped sockets, operations that cannot be completed immediately will be 
initiated, and completion will be indicated at a later time. The final completion status is 
retrieved through WSAGetOverlappedResult. The /ocbBytesReturned parameter is 
ignored. 


Any IOCTL may block indefinitely, depending on the service provider's implementation. If 
the application cannot tolerate blocking in a WSAloctl call, overlapped I/O would be 
advised for IOCTLs that are especially likely to block including: 


? SIO_FINDROUTE SIO_SET_QOS 
SIO_FLUSH — SIO_SET_ GROUP eles 
SIO_GET_QOS _ SIO_ROUTING_INTERFACE_CHANGE 


SIO_GET.GROUP_QOS =~—_ SIO_ADDRESS_LIST_CHANGE 
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Some protocol-specific IOCTLs may also be especially likely to block. Check the relevant 
protocol-specific annex for any available information. | 


It is possible to adopt an encoding scheme that preserves the currently defined 
loctlsocket opcodes while providing a convenient way to partition the opcode identifier 
space in as much as the dw/loContro/Code parameter is now a 32-bit entity. The 


_dwloControlCode parameter is built to allow for protocol and vendor independence when 


adding new control codes while retaining backward compatibility with the Windows 
Sockets 1.1 and Unix control codes. The dwloControlCode parameter has the 
following form. 


f O Vv T Vendor/address family code 


3 3 2 22 22222221111 111111 
1 O 9 87 65432109876. 5432109876543210 


| is set if the input buffer is valid for the code, as with IOC_IN. 


O is set if the output buffer is valid for the code, as with IOC_OUT. Codes with both 
input and output parameters set both I and O. 


V is set if there are no parameters for the code, as with lIOC_VOID. 
T is a 2-bit quantity that defines the type of IOCTL. The following values are defined: 
0 The IOCTL is a standard Unix lOCTL code, as with FIONREAD and FIONBIO. 


1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes 
defined for Windows Sockets 2 will have T == 1. 


2 The lIOCTL applies only to a specific address family. 


3 The IOCTL applies only to a specific vendor’s provider. This type allows companies 
to be assigned a vendor number that appears in the Vendor/Address family 
parameter. Then, the vendor can define new IOCTLs specific to that vendor without 
having to register the IOCTL with a clearinghouse, thereby providing vendor 
flexibility and privacy. 


Vendor/Address family An 11-bit quantity that defines the vendor who owns the code 
(if T == 3) or that contains the address family to which the code applies (if T == 2). If this 
is a Unix IOCTL code (T == 0) then this parameter has the same value as the code on 
Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this parameter can be 
used as an extension of the code parameter to provide additional code values. 


Code The 16-bit quantity that contains the specific |OCTL code for the operation. 
The following Unix IOCTL codes (commands) are supported. 


FIONBIO 
Enable or disable nonblocking mode on socket s. /pvinBuffer points at an unsigned 
long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be 
disabled. When a socket is created, it operates in blocking mode (that is, nonblocking 
mode is disabled). This is consistent with BSD sockets. | 
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The WSAAsyncSelect or WSAEventSelect routine automatically sets a socket to 
nonblocking mode. If WSAAsyncSelect or WSAEventSelect has been issued on a 
socket, then any attempt to use WSAloctl to set the socket back to blocking mode will 
fail with WSAEINVAL. To set the socket back to blocking mode, an application must 
first disable WSAAsyncSelect by calling WSAAsyncSelect with the /Event 
parameter equal to zero, or disable WSAEventSelect by calling WSAEventSelect 
with the /NetworkEvents parameter equal to zero. 


FIONREAD 
Determine the amount of data that can be read atomically from socket s. jovOutBuffer 
points at an unsigned long in which WSAloctl stores the result. If s is stream 
oriented (for example, type SOCK_STREAM), FIONREAD returns the total amount of 
data that can be read in a single receive operation; this is normally the same as the 
total amount of data queued on the socket (since data stream is byte-oriented, this is 
not guaranteed). If s is message oriented (for example, type SOCK_DGRAM), 
FIONREAD returns the size of the first datagram (message) queued on the socket. 


SIOCATMARK 

Determine whether or not all OOB data has been read. This applies only to a socket 
of stream-style (for example, tyoe SOCK_STREAM) that has been configured for — 
inline reception of any OOB data (SO_OOBINLINE). If no OOB data is waiting to be 
read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive 
operation performed on the socket will retrieve some or all of the data preceding the 

~ mark; the application should use the SIOCATMARK operation to determine whether 
any remains. If there is any normal data preceding the urgent (out of band) data, it will 
be received in order. (Note that recv operations will never mix OOB and normal data 
in the same call.) |pvOutBuffer points at a BOOL in which WSAloctl stores the result. 


The following Windows Sockets 2 commands are supported. 


SIO_ASSOCIATE_HANDLE (opcode setting: 1, T==1) __ 
Associate this socket with the specified handle of a companion interface. The input 
buffer contains the integer value corresponding to the manifest constant for the 
companion interface (for example, TH_NETDEV and TH_TAPI.), followed by a value 
that is a handle of the specified companion interface, along with any other required 
information. Refer to the appropriate section in the Windows Sockets 2 Protocol- 
Specific Annex (a separate document) for details specific to a particular companion 
interface. The total size is reflected in the input buffer length. No output buffer is 
required. The WSAENOPROTOOPT error code is indicated for service providers that 
do not support this ioctl. The handle associated by this ioctl can be retrieved using 
SIO_TRANSLATE_HANDLE. 


A companion interface might be used, for example, if a particular provider provides (1) 
a great deal of additional controls over the behavior of a socket and (2) the controls 
are provider-specific enough that they do not map to existing Windows Socket 
functions or ones likely to be defined in the future. It is recommend that the 
Component Object Model (COM) be used instead of this ioctl to discover and track 
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other interfaces that might be supported by a socket. This ioctl is present for (reverse) 
compatibility with systems where COM is not available or cannot be used for some 
other reason. 


SIO_ENABLE_CIRCULAR_QUEUEING (opcode setting: V, T==1) 
Indicates to the underlying message-oriented service provider that a newly arrived 
message should never be dropped because of a buffer queue overflow. Instead, the 
oldest message in the queue should be eliminated in order to accommodate the newly 
arrived message. No input and output buffers are required. Note that this ioctl is only 

_ valid for sockets associated with unreliable, message-oriented protocols. The 

WSAENOPROTOOPT error code is indicated for service providers that do not support 
this ioctl. | | 

SIO_FIND_ROUTE (opcode setting: O, T==1) 
When issued, this ioctl requests that the route to the remote address specified as a 
SOCKADDR in the input buffer be discovered. If the address already exists in the 
local cache, its entry is invalidated. In the case of Novell’s IPX, this call initiates an 
IPX GetLocalTarget (GLT), which queries the neers for the given remote address. 


SIO_FLUSH (opcode setting: V, T==1) 
Discards current contents of the sending queue associated with this socket. No input 
and output buffers are required. The WSAENOPROTOOPT error code is indicated for 
_service providers that do not support this ioctl. 

SIO_GET_BROADCAST_ADDRESS (opcode setting: O, T==1) 
This ioctl fills the output buffer with a SOCKADDR structure containing a suitable 
broadcast address for use with sendto/WSASendTo. 


SIO_GET_EXTENSION_FUNCTION_POINTER (opcode setting: O, |, T==1) 
Retrieve a pointer to the specified extension function supported by the associated 
service provider. The input buffer contains a globally unique identifier (GUID) whose 
value identifies the extension function in question. The pointer to the desired function 
is returned in the output buffer. Extension function identifiers are established by 
service provider vendors and should be included in vendor documentation that 
describes extension function capabilities and semantics. | 

SIO_GET_QOS (opcode setting: O, T==1) 
Reserved for future use with sockets. Retrieve the QOS structure associated with the 
socket. The input buffer is optional. Some protocols (for example, RSVP) allow the 
input buffer to be used to qualify a quality of service request. The QOS structure will 
be copied into the output buffer. The output buffer must be sized large enough to be 

able to contain the full QOS structure. The WSAENOPROTOOPT error code is 

_ indicated for service providers that do not support quality of service. 


A sender may not call SIO_GET_QOS until the socket is connected. 
A receiver may call SEO_GET_QOS soon as it is bound. 


SIO_GET_GROUP_QOS (opcode setting: O, |, T==1) 
Reserved. 
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SIO_MULTIPOINT_LOOPBACK (opcode setting: |, T==1) 
Controls whether data sent in a multipoint session will also be received by the same 
socket on the local host. A value of TRUE causes loopback reception to occur while a 
value of FALSE prohibits this. By default, loopback is enabled. 


SIO_MULTICAST_SCOPE (opcode setting: |, T==1) 
Specifies the scope over which multicast transmissions will occur. Scope is defined as 
the number of routed network segments to be covered. A scope of zero would 
indicate that the multicast transmission would not be placed on the wire but could be 
disseminated across sockets within the local host. A scope value of one (the default) — 
indicates that the transmission will be placed on the wire, but will not cross any _ 
routers. Higher scope values determine the number of routers that can be crossed. 
Note that this corresponds to the time-to-live (TTL) parameter in IP multicasting. By 
default, scope is 1. 


SIO_RCVALL 
Enables a socket to receive all IP packets on the network. The socket handle Lo 
to the WSAloctl function must be of AF_INET address family, SOCK_RAW socket 
type, and IPPROTO_IP protocol. The socket also must be bound to an explicit local 
interface, which means that you cannot bind to INADDR_ANY. 


Once the socket is bound and the ioctl set, calls to the WSARecv or recv furictions: 

return IP datagrams passing through the given interface. Note that you must supply a 
sufficiently large buffer. Setting this ioctl requires Administrator privilege on the local 

machine. SIO_RCVALL is available in Windows 2000 and later versions of Windows. 


~— SlO_ RCVALL_MCAST 
Enables a socket to receive all multicast IP traffic on the network (that is, all IP 
packets destined for IP addresses in the range of 224.0.0.0 to 239.255.255.255). The 
socket handle passed to the WSAloctl function must be of AF_INET address family, 
SOCK_RAW socket type, and IPPROTO_UDP protocol. The socket also must be 
bound to an explicit local interface, which means that you cannot bind to 
INADDR _ANY. | 


Once the socket i is bound and the ioctl set, calls to the WSARecv or recv functions 
return multicast. IP datagrams passing through the given interface. Note that you must 
supply a sufficiently large buffer. Setting this ioctl requires Administrator privilege on 
the local machine. SIO_RCVALL_MCAST is available only in Windows 2000 and 
later versions of Windows. 


— SIO_RCVALL_ IGMPMCAST | 
; Enables a socket to receive all IGMP. multicast IP traffic on the network, without. 
receiving other multicast IP traffic. The socket handle passed to the WSAloctl 
function must be of AF_INET address family, SOCK_RAW socket type, and. 
IPPROTO_IGMP protocol. The socket also must be bound to an explicit local 
interface, which means that you cannot bind to INADDR_ANY. _ 


‘Once the socket is bound and the ioctl set, calls to the WSARecv or recv functions | 
return multicast IP datagrams passing through the given interface. Note that you must 
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supply a sufficiently large buffer. Setting this ioctl requires Administrator privilege on 
the local machine. SIO_.RCVALL_IGMPMCAST is available only in Windows 2000 
and later versions of Windows. 


SIO_KEEPALIVE_VALS 
Enables the per-connection setting of keep-alive option, keepalive time, and 
keepalive interval. The argument structure for SIO_KEEPALIVE_VALS is as follows: 


SIO_SET_QOS (opcode setting: |, T==1) 
Associate the supplied QOS structure with the socket. No output buffer is required, 
the QOS structure will be obtained from the input buffer. The WSAENOPROTOOPT 
error code is indicated for service providers that do not support quality of service. 


SIO_SET_GROUP_QOS (opcode setting: |, T==1) 
Reserved. 


SIO_TRANSLATE_HANDLE (opcode setting: |, O, T==1) 
To obtain a corresponding handle for socket s that is valid in the context of a 
companion interface (for example, TH_NETDEV and TH_TAPI). A manifest constant 
identifying the companion interface along with any other needed parameters are 
specified in the input buffer. The corresponding handle will be available in the output | 
buffer upon completion of this function. Refer to the appropriate section in Windows 
Sockets 2 Protocol-Specific Annex for details specific to a particular companion 
interface. The WSAENOPROTOOPT error code is indicated for service providers that 
do not support this ioctl for the specified companion interface. This ioctl retrieves the 
handle associated using SIO_TRANSLATE_HANDLE. 


It is recommend that the Component Object Model (COM) be used instead of this ioctl 
to discover and track other interfaces that might be supported by a socket. This ioctl is 
present for backward compatibility with systems where COM is not available or cannot 
be used for some other reason. | | | 


SIO_ROUTING_INTERFACE_QUERY (opcode setting: |,O, T==1) 
To obtain the address of the local interface (represented as SOCKADDR structure) 
which should be used to send to the remote address specified in the input buffer (as 
SOCKADDR). Remote multicast addresses may be submitted in the input buffer to 
get the address of the preferred interface for multicast transmission. In any case, the 
interface address returned may be used by the application in a subsequent bind() 
request. a . 


Note that routes are subject to change. Therefore, applications cannot rely on the 
information returned by SIO_LROUTING_INTERFACE_QUERY to be persistent. 
Applications may register for routing change notifications through the 
SIO_ROUTING_INTERFACE_CHANGE IOCTL which provides for notification 
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through either overlapped I/O or FD_ROUTING_INTERFACE_CHANGE event. The 
following sequence of actions can be used to guarantee that the application aay 
has current routing interface information for a given destination: 


e Issue SIO_ROUTING_INTERFACE_CHANGE IOCTL 
e issue SIO_ROUTING_INTERFACE_ QUERY IOCTL 


e Whenever SIO _ROUTING_INTERFACE_CHANGE IOCTL notifies the application 
of routing change (either through overlapped I/O or by signaling 
FD_ROUTING_INTERFACE_CHANGE event), the whole sequence of actions 
should be repeated. 


If output buffer is not large enough to contain the interface address, 
SOCKET_ERROR is returned as the result of this IOCTL and WSAGetLastError 
returns WSAEFAULT. The required size of the output buffer will be returned in 
IpcbBytesReturned in this case. Note the WSAEFAULT error code is also returned if 
the /ovinBuffer, |pvOutBuffer or locbBytesReturned parameter is not totally contained 
in a valid part of the user address space. 


If the destination address specified in the input buffer cannot be reached through any 
of the available interfaces, SOCKET_ERROR is returned as the result of this IOCTL 
and WSAGetLastError returns WSAENETUNREACH or even WSAENETDOWN if all 

of the network connectivity is lost. | 


SIO_ROUTING_INTERFACE_CHANGE (opcode setting: |, T==1) 
To receive notification of the interface change that should be used to reach the 
remote address in the input buffer (specified as a SOCKADDR structure). No output 
information will be provided upon completion of this IOCTL; the completion merely 

_ indicates that routing interface for a given destination has changed and should be 
queried again through SIO_ROUTING_INTERFACE_QUERY. 


It is assumed (although not required) that the application uses overlapped I/O to be © 
notified of routing interface change through completion of 

~$IO_ROUTING_INTERFACE_CHANGE request. Alternatively, if the 

~ SIO_ROUTING_INTERFACE_CHANGE IOCTL is issued on nonblocking socket and 
without overlapped parameters (/pOverlapped / CompletionRoutine are set NULL), it — 
will complete immediately with error WSAEWOULDBLOCK, and the application can 

_ then wait for routing change events through call to WSAEventSelect or 
WSAAsyncSelect with FD_ROUTING_INTERFACE _CHANGE bit Set in the network 
event bitmask. 


It is recognized that routing information remains stable i in most cases so that requiring 
the application to keep multiple outstanding |OCTLs to get notifications about all 
destinations that it is interested in as well as having service provider to keep track of 
all them will unnecessarily tie significant system resources. This situation can be 
avoided by extending the meaning of the input parameters and reranng the service 
provider requirements as S follows: | 
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e The application can specify a protocol family specific wildcard address (same as 
one used in bind call when requesting to bind to any available address) to request 
notifications of any routing changes. This allows the application to keep only one 
outstanding SIO_ROUTING_INTERFACE_CHANGE for all the 
sockets/destinations it has and then use SIO_ROUTING_INTERFACE_QUERY to 
get the actual routing information. 


e Service provider has the option to ignore the information supplied by the 
application in the input buffer of the SIO_ROUTING_INTERFACE_CHANGE (as 
though the application specified a wildcard address) and complete the 
SIO_ROUTING_INTERFACE_CHANGE IOCTL or signal 
FD_ROUTING_INTERFACE_CHANGE event in the event of any routing 
information change (not just the route to the destination specified in the input 
buffer). 


SIO_ADDRESS_LIST_QUERY (opcode setting: |, O, T==1) 
To obtain a list of local transport addresses of the socket’s protocol family to which the 
application can bind. The list returned in the output buffer using the following format: 


Note In Win32 Plug-n-Play environments addresses can be added and removed 
dynamically. Therefore, applications cannot rely on the information returned by 
SIO_ADDRESS_LIST_QUERY to be persistent. Applications may register for 
address change notifications through the SIO_ADDRESS_LIST_CHANGE IOCTL 
which provides for notification through either overlapped I/O or 
FD_ADDRESS_LIST_CHANGE event. The following sequence of actions can be 
used to guarantee that the application always has current address list information: 


e Issue SIO_ADDRESS_LIST_CHANGE IOCTL 
¢ Issue SIO_ADDRESS_LIST_QUERY IOCTL 


e Whenever SIO_ADDRESS_LIST_CHANGE IOCTL notifies the application of 
address list change (either through overlapped I/O or by signaling 
FD_ADDRESS_LIST._CHANGE event), the whole sequence of actions should be 
repeated. | 


lf output buffer is not large enough to contain the address list, SOCKET_ERROR is 
returned as the result of this IOCTL and WSAGetLastError returns WSAEFAULT. 
The required size of the output buffer will be returned in jocbBytesReturned in this 
case. Note the WSAEFAULT error code is also returned if the IpvinBuffer, 
jovOutBuffer,or locbBytesReturned parameter is not totally contained in a valid part of 
the user address space. | 
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SIO_ADDRESS_LIST_CHANGE (opcode setting: T==1) 
To receive notification of changes in the list of local transport addresses of the 
socket’s protocol family to which the application can bind. No output information will 
be provided upon completion of this IOCTL; the completion merely indicates that list 
of available local address has changed and should be queried again through 
SIO_ADDRESS_LIST_QUERY. 


It is assumed (although not required) that the application uses overlapped I/O to be 
notified of change by completion of SIO_ADDRESS_LIST_CHANGE request. 
Alternatively, if the SIO_ADDRESS_LIST_CHANGE IOCTL is issued on a 

~ nonblocking socket and without overlapped parameters (/pOverlapped / 
loCompletionRoutine are set to NULL), it will complete immediately with error 
WSAEWOULDBLOCK. The application can then wait for address list change events 
through a call to WSAEventSelect or WSAAsyncSelect with 
FD_ADDRESS_LIST_CHANGE bit set in the network event bitmask. 


If an overlapped operation completes immediately, WSAloctl returns a value of zero and 
the IpcbBytesReturned parameter is updated with the number of bytes in the output 
buffer. If the overlapped operation is successfully initiated and will complete later, this 
function returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this 
case, locbBytesReturned is not updated. When the overlapped operation completes the 
amount of data in the output buffer is indicated either through the cbTransferred 
parameter in the completion routine (if specified), or through the pep nent parameter 
in WSAGetOverlappedResult. 


When called with an overlapped socket, the |pOverlapped parameter must be valid for 
the duration of the overlapped operation. The [pOverlapped parameter contains the 
address of a WSAOVERLAPPED structure. 


If the IpCompletionRoutine parameter is NULL, the Hevea nalameter * ipOvensbped! is 
signaled when the overlapped operation completes if it contains a valid event epee! 
handle. An application can use WSAWaitForMultipleEvents or 
WSAGetOverlappedResult to wait or poll on the event object. 


If JoCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used 
by the application to pass context information to the completion routine. A caller that — 
passes a non-NULL /pCompletionRoutine and later calls WSAGetOverlappedResult for 
the same overlapped I/O request may not set the fWait parameter for that invocation of © 
WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is 
undefined, and attempting to wait on the hEvent parameter would produce unpredictable 
results. 


The prototype of the completion routine is as follows: 


(continued) 
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(continued) 


This CompletionRoutine is a placeholder for an application-defined or library-defined 
function. The dwError parameter specifies the completion status for the overlapped 
operation as indicated by /pOverlapped. The cbTransferred parameter specifies the 
number of bytes returned. Currently, there are no flag values defined and dwFlags will 
be zero. The CompletionRoutine function does not return a value. 


Returning from this function allows invocation of another pending completion routine for 
this socket. The completion routines can be called in any order, not hecense lly in the 
same order the overlapped operations are completed. 


Compatibility 
The lIOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley 
sockets. In particular, there is no command that is equivalent to FIOASYNC. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, getsockopt, ioctlsocket, setsockopt, socket, WSASocket 


WSAIsBlocking 


This function has been removed in compliance with the ynGews Sockets 2 
specification, revision 2.2.0. 


The Windows Socket WSAIlsBlocking function is not exported aastiiy by the 
Ws2_32.dll, and Windows Sockets 2 applications should not use this function. Windows 


Sockets 1.1 applications that call this function are still supported through the Winsock.dll 
and Wsock32.dll. | | 


Blocking hooks are generally used to keep a single-threaded GUI application responsive 
during calls to blocking functions. Instead of using blocking hooks, an applications 
should use a separate thread (separate from the main GUI thread) for network activity. 
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WSAJoinLeaf 


The Windows Sockets WSAJoinLeaf function joins a leaf node into a multipoint session, 
| exchanges connect data, and specifies needed quality of service based on the supplied 
FLOWSPEC structures. 


Parameters - os 


Ss 
[in] Descriptor identifying a multipoint socket. 


name 
[in] Name of the peer to which the socket is to be joined. 


namelen 
[in] Length of name. 


[pCallerData 
in] Pointer to the user data that is to be transferred to the peer during multipoint 
session establishment. 


IpCalleeData 7 
[out] Pointer to the user data that is to be transferred back from the peer during 
multipoint session establishment. 


IpSQOS 
[in] Pointer to the FLOWSPEC structures for socket s, one for each direction. 


IpGQOS 7 | 3 | 
[in] Reserved. 


dwFlags 
— [in] Flags to indicate that the socket is acting as a sender, receiver, or both. 


Return Values ae 8 | | > 


If no error occurs, WSAJoinLeaf returns a value of type SOCKET that is a descriptor for 
the newly created multipoint socket. Otherwise, a value of INVALID_SOCKET is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. | 


On a blocking socket, the return value indicates success or failure of the join operation. 
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With a nonblocking socket, successful initiation of a join operation is indicated by a 
return of a valid socket descriptor. Subsequently, an FD_CONNECT indication will be 
given on the original socket s when the join operation completes, either successfully or 
otherwise. The application must use either WSAAsyncSelect or WSAEventSelect with 
interest registered for the FD_CONNECT event in order to determine when the join 
operation has completed and checks the associated error code to determine the success 
or failure of the operation. The select function cannot be used to determine when the 
join operation completes. 


Also, until the multipoint session join sonnel completes all subsequent callsto | 
WS<AJoinLeaf on the same socket will fail with the error code WSAEALREADY. After 
the WSAJoinLeaf operation completes successfully, a subsequent attempt will usually 
fail with the error code WSAEISCONN. An exception to the WSAEISCONN rule occurs 
for a c_root socket that allows root-initiated joins. In such a case, another join may be 
initiated after a prior WSAdJoinLeaf operation completes. 


lf the return error code indicates the multipoint session join attempt failed (that is, 
WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application can 
call WSAJoinLeaf again for the same socket. 


Error code | Meaning | 
WSANOTINITIALISED A successful WSAStartup call must occur before 

| using this function. 
WSAENETDOWN | The network subsystem has failed. 
WSAEADDRINUSE _ The socket’s local address is already in use and the 


socket was not marked to allow address reuse with 
SO_REUSEADDR. This error usually occurs at the 
time of bind, but could be delayed until this function 
if the bind was to a partially wildcard address 
(involving ADDR_ANY) and if a specific address 
~ needs to be committed at the time of this function. 


WSAEINTR ~ Ablocking Windows Socket 1.1 call was canceled 
| | through WSACancelBlockingCall. 
WSAEINPROGRESS ~ A blocking Windows Sockets 1.1 call is in progress, 
| | or the service provider is still processing a callback 
| function. 
WSAEALREADY A nonblocking WSAJoinLeaf call is in progress on 
e yen the specified socket. 
WSAEADDRNOTAVAIL The remote address is not a valid address (such as — 
: : | ADDR_ANY). | | | 
WSAEAFNOSUPPORT Addresses in the specified family cannot be used 


with this socket. 
WSAECONNREFUSED- The attempt to join was forcefully rejected. 
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Error code Meaning 


WSAEFAULT The name or the namelen parameter is not a valid 
: part of the user address space, the namelen 
parameter is too small, the buffer length for 
IpCalleeData, |IpDSQOS, and |[pPGQOS are too small, 
or the buffer length for /pCallerData is too large. 


WSAEISCONN | The socket is already a member of the multipoint 
| | session. 
WSAENETUNREACH The network cannot be reached from this host at 
| this time. | 
WSAENOBUFS No buffer space is available. The socket cannot be 
| joined. 
| WSAENOTSOCK The descriptor is not a socket. | 

WSAEOPNOTSUPP _ The FLOWSPEC structures specified in JoOSQOS and 


‘|o>GQOS cannot be satisfied. 


WSAEPROTONOSUPPORT The /pCallerData augment is not sunncnea by the 
service provider. 


WSAETIMEDOUT The attempt to join timed out without establishing a 
multipoint session. 


Remarks 

The WSAJoinLeaf function is used to join a leaf node to a multipoint session, and to 

perform a number of other ancillary operations that occur at session join time as well. If 
the socket, s, is unbound, unique values are assigned to the local association by the 

system, and the socket is marked as bound. . 


The WSAJoinLeaf function has the same parameters and semantics as WSAConnect 
except that it returns a socket descriptor (as in WSAAccept), and it has an additional 
dwFlags parameter. Only multipoint sockets created using WSASocket with appropriate 
multipoint flags set can be used for input parameter s in this function. The returned 

- socket descriptor will not be useable until after the join operation completes. For 
example, if the socket is in nonblocking mode after a corresponding FD_CONNECT _ 
indication has been received from WSAAsyncSelect or WSAEventSelect on the | 
original socket s, except that closesocket may be invoked on this new socket descriptor 
to cancel a pending join operation. A root application in a multipoint session may call 
WSAdJoinLeaf one or more times in order to add a number of leaf nodes, however at 
most one multipoint connection request may be outstanding ata time. Refer to Multipoint 
and Multicast Semantics for additional information. 


For nonblocking sockets itis often not possible to complete the connection immediately. 
In such a case, this function returns an as-yet unusable socket descriptor and the 
operation proceeds. There is no error code such as WSAEWOULDBLOCK in this case, 
since the function has effectively returned a successful start indication. When the. final 

7 outcome Success or failure becomes known, it may be reported through 
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WSAAsyncSelect or WSAEventSelect depending on how the client registers for 
notification on the original socket s. In either case, the notification is announced with 
FD_CONNECT and the error code associated with the FD_CONNECT indicates either 
success or a specific reason for failure. The select function cannot be used to detect 
completion notification for WSAJoinLeaf. 


The socket descriptor returned by WSAJoinLeaf is different depending on whether the 
input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the 
name parameter designates a particular leaf node to be added and the returned socket 
descriptor is a c_leaf socket corresponding to the newly added leaf node. The newly 
created socket has the same properties as s, including asynchronous events registered 
with WSAAsyncSelect or with WSAEventSelect. It is not intended to be used for 
exchange of multipoint data, but rather is used to receive network event indications (for 
example, FD_CLOSE) for the connection that exists to the particular c_leaf. Some 
multipoint implementations can also allow this socket to be used for side chats between 
the root and an individual leaf node. An FD_CLOSE indication will be received for this 
socket if the corresponding leaf node calls closesocket to drop out of the multipoint 
session. Symmetrically, invoking closesocket on the c_leaf socket returned from 
WS<AJoinLeaf will cause the socket in the corresponding leaf node to get an 
FD_CLOSE notification. | 


When WSAvoinLeaf is invoked with a c_leaf socket, the name parameter contains the 
address of the root application (for a rooted control scheme) or an existing multipoint 
session (nonrooted control scheme), and the returned socket descriptor is the same as 
the input socket descriptor. In other words, a new socket descriptor is not allocated. Ina 
rooted control scheme, the root application would put its c_root socket in listening mode 
by calling listen. The standard FD_ACCEPT notification will be delivered when the leaf 
node requests to join itself to the multipoint session. The root application uses the usual 
accept/WSAAccept functions to admit the new leaf node. The value returned from 
either accept or WSAAccept is also a c_leaf socket descriptor just like those returned 
from WSAJoinLeaf. To accommodate multipoint schemes that allow both root-initiated 
and leaf-initiated joins, it is acceptable for a c_root socket that is already in listening 
mode to be used as an input to WSAJoinLeaf. 


The application is responsible for allocating any memory space pointed to directly or 
indirectly by any of the parameters it specifies. 


: The |pCallerData is a value parameter that contains any user data that is to be sent 
along with the multipoint session join request. If |oCallerData is NULL, no user data will 


be passed to the peer. The /pCa/leeData is a result parameter that will contain any user 
data passed back from the peer as part of the multipoint session establishment. The 
lpCalleeData->len initially contains the length of the buffer allocated by the application 
and pointed to by /oCalleeData->buf. loCalleeData->/en will be set to zero if no user data 
has been passed back. The /pCalleeData information will be valid when the multipoint 
join operation is complete. ine | 
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For blocking sockets, this will be when the WSAJoinLeaf function returns. For 
nonblocking sockets, this will be after the join operation has completed. For example, 
this could occur after FD_CONNECT notification on the original socket s). If 
IoCalleeData is NULL, no user data will be passed back. The exact format of the user 
data is specific to the address family to which the socket belongs. 


At multipoint session establishment time, an application can use the |oOSQOS parameter 
to override any previous quality of service specification made for the socket through 
WSAloctl with the SIO_SET_QOS opcode. 


The jJoSQOS parameter specifies the FLOWSPEC structures for socket s, one for each 
direction, followed by any additional provider-specific parameters. If either the associated 
transport provider in general or the specific type of socket in particular cannot honor the 
quality of service request, an error will be returned as indicated in the following. The 
respective sending or receiving flow specification values will be ignored for any 
unidirectional sockets. If no provider-specific parameters are supplied, the buf and /en 
parameters of |pDSQOS->ProviderSpecific should be set to NULL and zero, respectively. 
A NULL value for JoOSQOS indicates no application-supplied quality of service. 


The dwFlags parameter is used to indicate whether the socket will be acting only as a 
sender (JL_SENDER_ONLY), only as a receiver (JL_RECEIVER_ONLY), or both 
(JL_BOTH). 


When connected sockets break (that is, become closed for whatever reason), they 
should be discarded and recreated. It is safest to assume that when things go awry for 
any reason on a connected socket, the application must discard and recreate the 
needed sockets in order to return to a stable point. 


Version: Requires Windows Sockets 2.0. 
‘Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, accept, bind, select, WSAAccept, WSAAsyncSelect, 
WSAEventSelect, WSASocket 


WSALookupServiceBegin 
The Windows Sockets WSALookupServiceBegin function initiates a client query that is 
constrained by the information contained within a WSAQUERYSET structure. 


WSALookupServiceBegin only returns a handle, which should be used by subsequent 
calls to Meo r conupee cones to get the actual results. 
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Parameters : 
lpqsRestrictions 

[in] Pointer to the search criteria. See the following for details. 
dwControlFlags 

in] Flag that controls the depth of the search: 

Flag Description 

LUP_DEEP Queries deep as opposed to just the first level. 


LUP_CONTAINERS 
LUP_NOCONTAINERS 
LUP_FLUSHCACHE 


LUP_FLUSHPREVIOUS 


LUP_NEAREST 


LUP_RES_SERVICE 


LUP_RETURN_ALIASES 


LUP_RETURN_NAME 


LUP_RETURN_TYPE 
LUP_RETURN_VERSION 
LUP_RETURN_COMMENT 
LUP_RETURN_ADDR 
LUP_RETURN_BLOB 
LUP_RETURN_ALL 


Returns containers only. 
Does not return any containers. 


If the provider has been caching information, 
ignores the cache, and queries the name space 
itself. 


Used as a value for the dwControlFlags argument 
in WSALookupServiceNext. Setting this flag 
instructs the provider to discard the last result set, 
which was too large for the supplied buffer, and 
move on to the next result set. 


If possible, returns results in the order of 
distance. The measure of distance is provider 
specific. 


This indicates whether prime response is in the 
remote or local part of CSADDR_INFO structure. 
The other part needs to be usable in either case. 


Any available alias information is to be returned 
in successive calls to WSALookupServiceNext, 
and each alias returned will have the 
RESULT_IS_ALIAS flag set. 


Retrieves the name as 
lpszServicelnstanceName. 


Retrieves the type as /pServiceClassld. 
Retrieves the version as /pVersion. 
Retrieves the comment as /pszComment. 
Retrieves the addresses as /pcsaBuffer. 
Retrieves the private data as /pBlob. 
Retrieves all of the information. 
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lohLookup 
[out] Handle to be used when calling WSALookupServiceNext in order to start 
retrieving the results set. 


Return Values 

The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 
WSAGetLastError. 


Error code Meaning 
WSAEINVAL One or more parameters were missing or invalid 
for this provider. 
WSANO_DATA The name was found in the database but no data 
| ~ matching the given restrictions was located. 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Sockets functions. 


WSASERVICE_NOT_FOUND ~ No such service is known. The service cannot be 
| ar +e _ found in the specified name space. 

~WSA NOT ENOUGH MEMORY _ There was insufficient memory to perform the 
| | a operation. | 

Remarks 


If LUP_ _CONTAINERS | is specified | in a call, all other restriction values should be 
avoided. If any are supplied, it is up to the name service provider to decide if it can 
support this restriction over the containers. If it cannot, it should return an error. 


Some name service providers can have other means of finding containers. For example, 
containers might all be of some well-known type, or of a set of well-known types, and 
therefore a query restriction can be created for finding them. No matter what other 
means the name service provider has for locating containers, LUP_CONTAINERS and 
LUP_NOCONTAINERS take precedence. Hence, if a query restriction is given that 
includes containers, specifying LUP_NOCONTAINERS will prevent the container items 
from being returned. Similarly, no matter the query restriction, if LUP_CONTAINERS is 
given, only containers should be returned. If a name space does not support containers, 
and LUP_CONTAINERS is specified, it should simply return WSANO_DATA. 


The preferred method of obtaining the containers within another container, is the call: 
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This call is followed by the requisite number of WSALookupServiceNext calls. This will 
return all containers contained immediately within the starting context; that is, it is nota 
deep query. With this, one can map the address space structure by walking the 
hierarchy, perhaps enumerating the content of selected containers. Subsequent uses of 
WSALookupServiceBegin use the containers returned from a previous call. 


As mentioned above, a WSAQUERYSET structure is used as an input parameter to 
WSALookupBegin in order to qualify the query. The following table indicates how the 
WSAQUERYSET is used to construct a query. When a parameter is marked as 
(Optional) a NULL pointer can be supplied, indicating that the parameter will not be used 
as a search criteria. See section Query-Related Data Structures for additional 


information. 


WSAQUERYSET member 
name 


dwSize 


dwOutputflags — 
LpszServicelnstanceName 


LpServiceClassld 


LpVersion 


LpszComment 
DwNameSpace! 


LpNSProviderld 


LpszContext 


DwNumberOfProtocols 
LpafpProtocols 


Query interpretation 


Must be set to sizeof(WSAQUERYSET). This is a 
versioning mechanism. 


Ignored for queries. 


(Optional) Referenced string contains service name. 
The semantics for wildcarding within the string are 
not defined, but can be supported by certain name 
space providers. 


(Required) The GUID corresponding to the service 
class. 


(Optional) References desired version number and 
provides version comparison semantics (that is, 
version must match exactly, or version must be not 
less than the value supplied). | 


Ignored for queries. 


Identifier of a single name space in which to 
constrain the search, or NS_ALL to include all name 
spaces. | 

(Optional) References the GUID of a specific name 
space provider, and limits the query to this 

provider only. 3 

(Optional) Specifies the starting point of the query in 
a hierarchical name space. 

Size of the protocol constraint array, can be Zero. 
(Optional) References an array of AFPROTOCOLS 
structure. Only services that utilize these protocols 
will be returned. 
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WSAQUERYSET member 

name Query interpretation 

LpszQueryString (Optional) Some name spaces (such as whois++) 
support enriched SQL-like queries that are contained 

ina simple text string. This parameter is used to 

specify that string. 

DwNumberOfCsAddrs Ignored for queries. 

LpcsaBuffer | Ignored for queries. 

LpBlob (Optional) This is a pointer to a provider-specific 
entity. 


1 See the Important note that follows. 


Important In most instances, applications interested in only a particular transport 

_ protocol should constrain their query by address family and protocol rather than by name 
space. This would allow an application that needs to locate a TCP/IP service, for 
example, to have its query processed by all available name spaces such as the local 
hosts file, DNS, and NIS. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 

Unicode; Implemented as Unicode and ANSI versions on Windows NT/2000. 


WSALookupServiceEnd, WSALookupServiceNext 


-WSALookupServiceEnd 


The Windows Sockets WSALookupServiceEnd function is called to free the handle 
after previous calls to WSALookupServiceBegin and WSALookupServiceNext. 


lf you call WSALookupServiceEnd from another thread while an existing 
~WSALookupServiceNext is blocked, the end call will have the same effect as a cancel 
and will cause the WSALookupServiceNext call to return immediately. 
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Parameters 


hLookup 
[in] Handle previously obtained by calling WSALookupServiceBegin. 


Return Values 
The return value is zero if the operation was successful. Otherwise, the value 


SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 
WSAGetLastError. 


Error code — | Meaning 
WSA_INVALID HANDLE The handle is not valid. 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Sockets functions. 


WSA NOT ENOUGH MEMORY There was insufficient memory to perform the 
operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


WSALookupServiceBegin, WSALookupServiceNext 


WSALookupServiceNext 


The Windows Sockets WSALookupServiceNext function is called after obtaining a 
handle from a previous call to WSALookupServiceBegin in order to retrieve the 
requested service information. 


The provider will pass back a WSAQUERYSET structure in the /oqsResults buffer. The 
client should continue to call this function until it returns WSA_E_ _NOMORE, indicating 


| that all of WSAQUERYSET has been returned. 
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Parameters 


hLookup 
[in] Handle returned from the previous call to WSALookupServiceBegin. 


dwControlFlags 
[in] Flags to control the next operation. Currently only LUP_FLUSHPREVIOUS is | 
defined as a means to cope with a result set which is too large. If an application does 
not wish to (or cannot) supply a large enough buffer, setting LUP_FLUSHPREVIOUS 
instructs the provider to discard the last result set—which was too large—and move | 
on to the next set for this call. 


lodwBufferLength 
[in/out] On input, the number of bytes contained in the buffer pointed to by 
loqsResults. On output, if the function fails and the error is WSAEFAULT, then it 
contains the minimum number of bytes to pass for the JogsResults to retrieve the 
record. | | 


logsResults | 
[out] Pointer to a block of memory, “which will conten one result set ina 
WSAQUERYSET structure on return. | 


Return Values 


The return value is zero if the operation was successful. Otherwise, the value | : 
SOCKET_ERROR i is returned, and a specific error number can 1 be retrieved by calling 


| WSAGetLastError. | 
Errorcode | eg Meaning | | 
WSA_E_NO MORE | | There is no more data available. In Windows Sockets version 2, 


conflicting error codes are defined for WSAENOMORE (10102) 
and WSA_E_NO_MORE (10110). The error code © | 
WSAENOMORE will be removed in a future version and only 
WSA_E_NO_MORE will remain. For Windows Sockets version 
2, however, applications should check for both WSAENOMORE 
and WSA_E_NO_MORE for the widest possible compatibility 
with name-space providers that use either one. 


WSA_E_CANCELLED A call to WSALookupServiceEnd was made while this call was 

| | still processing. The call has been canceled. The data in the 
lpqsResults buffer is undefined. In Windows Sockets version 2, 
conflicting error codes are defined for WSAECANCELLED 
(10103) and WSA_E_CANCELLED (10111). The error code 

~ WSAECANCELLED will be removed in a future version and only 

WSA_E_CANCELLED will remain. For Windows Sockets version 
2, however, applications should check for both i 
WSAECANCELLED and WSA_E_CANCELLED for the widest 
possible compatibility with name space providers that use 
either one. 3 


~ (continued) 
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(continued) 

Error code Meaning 

WSAEFAULT | The /pgsResults buffer was too small to contain a 
WSAQUERYSET set. 

WSAEINVAL One or more required parameters were invalid or missing. 

WSA_INVALID_HANDLE The specified Lookup handle is invalid. | 

WSANOTINITIALIZED ‘The Ws2_32.dll has not been initialized. The application must 
first call WSAStartup before calling any Windows Sockets 
functions. | 

WSANO_DATA The name was found in the database, but no data matching the 


given restrictions was located. 


WSASERVICE_NOT FOUND No such service is known. The service cannot be found in the 
specified name space. | 


WSA NOT ENOUGH There was insufficient memory to perform the operation. 
MEMORY 


Remarks 


The dwControlFlags parameter specified in this function and the ones specified at the 
time of WSALookupServiceBegin are treated as restrictions for the purpose of 
combination. The restrictions are combined between the ones at 
WSALookupServiceBegin time and the ones at WSALookupServiceNext time. 
Therefore the flags at WSALookupServiceNext can never increase the amount of data 
returned beyond what was requested at WSALookupServiceBegin, although it is not 
an error to specify more or fewer flags. The flags specified at a given 
WSALookupServiceNext apply only to that call. 


The dwControlFlags LUP_FLUSHPREVIOUS and LUP_RES_SERVICE are exceptions 
to the combined restrictions rule (because they are behavior flags instead of restriction 
flags). If either of these flags are used in WSALookupServiceNext they have their 
defined effect regardless of the setting of the same flags at WSALookupServiceBegin. 


For example, if LUP_RETURN_VERSION is specified at WSALookupServiceBegin the 
service provider retrieves records including the version. If LUP_RETURN_VERSION is 
NOT specified at WSALookupServiceNext, the returned information does not include 
the version, even though it was available. No error is generated. 


Also for example, if LU P_RETURN_BLOB is NOT specified at | 
WSALookupServiceBegin but is specified at WSALookupServiceNext, the returned 
information does not include the private data. No error is generated. 


Query Results se a 
The following table describes how the query results are represented in the 
WSAQUERYSET structure. 


WSAQUERYSET member 
name 


dwSize 


dwOuputFlags 
LpszServicelnstanceName 
LpServiceClasslid 
LpVersion 

LpszComment 
DwNameSpace 
LpNSProviderld 


LpszContext 


DwNumberOfProtocols 
lpafpProtocols 


LpszQueryString 


DwNumberOfCsAddrs 
LpcsaBuffer 


LpBlob 
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Result interpretation 


Will be set to Sea ee neoe This is used as a 
versioning mechanism. 


RESULT_IS_ALIAS flag indicates this is an alias result. 
Referenced string contains service name. 

The GUID corresponding to the service class. 

References version number of the particular service instance. 
Optional comment string supplied by service instance. 

Name space in which the service instance was found. 


Identifies the specific name space provider that eee this 
query result. 


Specifies the context point in a hierarchical name space at 
which the service is located. 


Undefined for results. 


Undefined for results, all needed protocol information is in the 
CSADDR_INFO structures. 


When dwControlFlags includes 
LUP_RETURN_QUERY_STRING, this parameter returns the 
unparsed remainder of the /pszServiceinstanceName specified 
in the original query. For example, in a name space that 
identifies services by hierarchical names that specify a host 
name and a file path within that host, the address returned might 


_ be the host address and the unparsed remainder might be the 


file path. If the IoszServiceinstanceName is fully parsed and 
LUP_RETURN_QUERY_STRING is used, this parameter is 
NULL or points to a zero-length string. 

Indicates the number of elements in the array of 
CSADDR_INFO structures. 

A pointer to an array of CSADDR_INFO structures, with one 
complete transport address contained within each element. 


| (Optional) This is a pointer to a provider-specific entity. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 
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WSALookupServiceBegin, WSALookupServiceEnd 


WSANtohI 


The Windows Sockets WSANtohlI function converts a u_long from network byte order to 
host byte order. 


Parameters 
S 


[in] Descriptor identifying a socket. 


netlong 
[in] 32-bit number in network byte order. 


Iphostlong 
[out] Pointer to a 32-bit number in host byte order. 


Return Values , 


If no error occurs, WSANtohlI returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error code Meaning 


WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. | 


WSAENETDOWN The network subsystem has failed. 
-WSAENOTSOCK The descriptor is not a socket. | 
WSAEFAULT The /phostlong parameter is not completely 7 

contained in a valid part of the user address space. 
Remarks 


The WSANtohlI function takes a 32-bit number in the network byte order associated with 
socket s and returns a 32-bit number pointed to by the /phostiong parameter in host byte 
order. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, htonl, htons, ntohl, ntohs, WSAHtonI, WSAHtons, WSANtohs 


WSANtohs : 


The Windows Sockets WSANtohs function converts a u_short from network byte order 
to host byte order. 


Parameters 


S : : 
[in] Descriptor identifying a socket. 


netshort a | 
~ [in] 16-bit number in network byte order. 


lphostshort 
[out] Pointer to a 16-bit number in host byte order. 


Return Values 


If no error occurs, WSANtohs returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code can be retrieved by calling WSAGetLastError. 


Error Codes 

Error code | Meaning © 

WSANOTINITIALISED ~ Asuccessful WSAStartup call must occur before 
using this function. 

WSAENETDOWN | The network subsystem has failed. 

WSAENOTSOCK > | The descriptor is not a socket. 

WSAEFAULT _ | _ The /phostshort parameter is not completely 


contained in a valid part of the user address space. 
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Remarks 


The WSANtohs function takes a 16-bit number in the network byte order associated with 
socket s and returns a 16-bit number pointed to by the /ohostshort parameter in host 
byte order. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, htonl, htons, ntohl, ntohs, WSAHtonI, WSANtohI, WSAHtons 


WSAProviderConfigChange 


The Windows Sockets WSAProviderConfigChange function notifies the application 
when the provider configuration is changed. | 


Parameters 


loNotificationHandle 
[in/out] Pointer to notification handle. If the notification handle is set to NULL (the 
handle value not the pointer itself), this function returns a notification handle in the 
location pointed to by /pNotificationHandle. | 

lpOverlapped © 
[in] Pointer to a WSAOVERLAPPED structure. 


loCompletionRoutine 
[in] Pointer to the completion routine called when the provider change notification is 


received. 


Return Values | | | 

If no error occurs the WSAProviderConfigChange returns 0. Otherwise, a value of 
SOCKET_ERROR is returned and a specific error code may be retrieved by calling 
WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped 
operation has been successfully initiated and that completion (and thus change event) 
will be indicated at a later time. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur 
| | before using this function. 

WSAENETDOWN The network subsystem has failed. 


WSA_NOT_ENOUGH_MEMORY Not enough free memory available to complete 
the operation. 


WSA_INVALID_ HANDLE Value pointed by /pNotificationHandle parameter 
- is not a valid notification handle. 
WSAEOPNOTSUPP | Current operating system environment does not 
support provider installation or removal without 
restart. 
Remarks 


The WSAProviderConfigChange function notifies the application of provider (both 
transport and name-pace) installation or removal in Win32 operating environments that 
support such configuration change without requiring a restart. When called for the first 
time (/oNotificationHandle parameter points to NULL handle), this function completes 
immediately and returns notification handle in the location pointed by 
IpNotificationHandle that can be used in subsequent calls to receive notifications of 
provider installation and removal. The second and any subsequent calls only complete 
_ when provider information changes since the time the call was made It is expected (but 
not required) that that application uses overlapped I/O on second and subsequent calls 
to WSAProviderConfigChange, in which case the call will return immediately and 
application will be notified of provider configuration changes using the completion 
mechanism chosen through specified overlapped completion parameters. 


Notification handle returned by WSAProviderConfigChange is like any regular 
operating system handle that should be closed (when no longer needed) using Win32 
CloseHandle call. 


The following sequence of actions can be used to guarantee that application always has 
current protocol configuration information: 


e Call WSAProviderConfigChange — 
~@ Call WSAEnumProtocols and/or WSAEnumNameSpaceProviders — 


e@ Whenever WSAProviderConfigChange notifies application of provider configuration 
change (through blocking or overapped I/O), the whole Se eis of actions should 
be epee’ 7 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws_32.lib. 
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Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSAEnumProtocols, WSAEnumNameSpaceProviders 


WSARecv 


The Windows Sockets WSARecv function receives data from a connected socket. 


a 


RSs 


S | : | 
in] Descriptor identifying a connected socket. 


loBuffers | 
in/out] Pointer to an array of WSABUF structures. Each WSABUF structure contains 
| a pointer to a buffer and the length of the buffer. 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesRecvd | | | — 


[out] Pointer to the number of bytes received by this call if the receive operation 
completes immediately. | 


IpFlags | : 
in/out] Pointer to flags. i 


lpOverlapped 
[in] Pointer toa WSAOVERLAPPED structure (ignored for nonoverlapped sockets). 


lpCompletionRoutine | sO 3A Bisaes ad 
in] Pointer to the completion routine called when the receive operation has been 
completed (ignored for nonoverlapped sockets). 


Return Values | a 


If no error occurs and the receive operation has completed immediately, WSARecv 
returns zero. In this case, the completion routine will have already been scheduled to be 
called once the calling thread is in the alertable state. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
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WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped 
operation has been successfully initiated and that completion will be indicated at a later 
time. Any other error code indicates that the overlapped operation was not successfully 
initiated and no completion indication will occur. 


Error code 


WSANOTINITIALISED 


WSAENETDOWN 
WSAENOTCONN 
WSAEINTR 


WSAEINPROGRESS 
WSAENETRESET 


WSAENOTSOCK ~ 
WSAEFAULT 


WSAEOPNOTSUPP 
WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


WSAEINVAL 
WSAECONNABORTED 
WSAECONNRESET 
WSAEDISCON 


Meaning 

A successful WSAStartup call must occur before using this 
function. 

The network subsystem has failed. 

The socket is not connected. 


The (blocking) call was canceled through 
WSACancelBlockingCall. 


A blocking Windows Sockets 1.1 call is in progress, or the service 
provider is still processing a callback function. 


The connection has been broken due to keep-alive activity 
detecting a failure while the operation was in progress. 


The descriptor is not a socket. 


The /pBuffers parameter is not completely contained in a valid part 
of the user address space. 


~MSG_OOB was specified, but the socket is not stream-style such | 


as type SOCK_STREAM, OOB data is not supported in the 
communication domain associated with this socket, or the socket . 
is unidirectional and supports only send operations. 

The socket has been shut down; it is not possible to call 
WSARecv on a socket after shutdown has been invoked with 
how set to SD_RECEIVE or SD_BOTH. 

Overlapped sockets: there are too many outstanding overlapped 
I/O requests. Nonoverlapped sockets: The socket is marked as 
nonblocking and the receive operation cannot be completed 
immediately. | 

The message was too large to fit into the specified buffer and (for 
unreliable protocols only) any trailing portion of the message that © 
did not fit into the buffer has been discarded. 

The socket has not been bound (for example, with bind). 

The virtual circuit was terminated due to a time-out or other failure. 
The virtual circuit was reset by the remote side. 


Socket s is message oriented and the virtual circuit was gracefully 
closed by the remote side. 


: ontintiod: 


328 Volume 1 Winsock and QOS 

(continued) 
Error code | Meaning 
WSA_IO_PENDING An overlapped operation was successfully initiated and 

completion will be indicated at a later time. 

WSA_OPERATION_ The overlapped operation has been canceled due to the closure 
ABORTED of the socket. 

Remarks 


The WSARecv function provides functionality over and above the standard recv function 
in three important areas: 


e |t can be used in conjunction with overlapped sockets to perform overlapped recv 
operations. 


e |t allows multiple receive buffers to be specified making it applicable to the 
scatter/gather type of I/O. 


e The /pFlags parameter is both an input and an output parameter, allowing applications 
to sense the output state of the MSG_PARTIAL flag bit. However, the MSG_PARTIAL 
flag bit is not supported by all protocols. 


The WSARecv function is used on connected sockets or bound connectionless sockets 
specified by the s parameter and is used to read incoming data. The socket’s local 
address must be known. For server applications, this is usually done explicitly through 
bind or implicitly through accept or WSAAccept. Explicit binding is discouraged for 
client applications. For client applications the socket can become bound implicitly to a 
local address through connect, WSAConnect, sendto, WSASendTo, or 
WSAJoinLeaf. 


For connected, connectionless sockets, this function restricts the addresses from which 
received messages are accepted. The function only returns messages from the remote 
address specified in the connection. Messages from other addresses are (silently) 
discarded. 


For overlapped sockets, WSARecv is used to post one or more buffers into which 
incoming data will be placed as it becomes available, after which the application- 
specified completion indication (invocation of the completion routine or setting of an 
event object) occurs. If the operation does not complete immediately, the final 
completion status is retrieved through the Eolnpignon routine or 
WSAGetOverlappedResult. 


If both /pOverlapped and |pCompletionRoutine are ae the socket in this function will © 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the blocking semantics are identical to that of the standard 
recv function and the /pOverlapped and |oCompletionRoutine parameters are ignored. 
Any data that has already been received and buffered by the transport will be copied into 
the supplied user buffers. In the case of a blocking socket with no data currently having 
been received and buffered by the transport, the call will block until data is received. 
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Windows Socket 2 does not define any standard blocking time-out mechanism for this 
function. For protocols acting as byte-stream protocols the stack tries to return as much 
data as possible subject to the supplied buffer soace and amount of received data 
available. However, receipt of a single byte is sufficient to unblock the caller. There is no 
guarantee that more than a single byte will be returned. For protocols acting as 
message-oriented, a full message is required to unblock the caller. 


Whether or not a protocol is acting as byte stream is determined by the setting of 
XP1_MESSAGE_ORIENTED and XP1_PSEUDO_STREAM in its 
WSAPROTOCOL_INFO structure and the setting of the MSG_PARTIAL flag passed in 
to this function (for protocols that support it). The relevant combinations are summarized 
in the following table, (an asterisk “*” indicates that the setting of this bit does not matter 
in this case). : 


XP1_MESSAGE _ XP1_PSEUDO _ | 
ORIENTED | STREAM MSG_PARTIAL Acts as 


not set , : byte stream 
i set 7 | byte stream 
set -— notset set | byte stream 
set not set | not set message oriented 


The supplied buffers are filled in the order in which they appear in the array pointed to by 
loBuffers, and the buffers are packed so that no holes are created. 


The array of WSABUF siructures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider's 

‘responsibility to capture these WSABUF structures before returning from this call. This 
enables applications to build stack-based WSABUF arrays. 


For byte stream-style sockets (for example, tyoe SOCK_STREAM), incoming data is 
placed into the buffers until the buffers are filled, the connection is closed, or the 
internally buffered data is exhausted. Regardless of whether or not the incoming data 
fills all the buffers, the completion indication occurs for overlapped sockets. 


For message-oriented sockets (for example, type SOCK_DGRAM), an incoming 
message is placed into the supplied buffers up to the total size of the buffers supplied, 
and the completion indication occurs for overlapped sockets. If the message is larger 
than the buffers supplied, the buffers are filled with the first part of the message. If the 
MSG_PARTIAL feature is supported by the underlying service provider, the 
MSG_PARTIAL flag is set in JpFlags and subsequent receive operations will retrieve the 
rest of the message. If MSG_PARTIAL is not supported but the protocol is reliable, 
WSARecv generates the error WSAEMSGSIZE and a subsequent receive operation 
with a larger buffer can be used to retrieve the entire message. Otherwise, (that is, the 
protocol is unreliable and does not support MSG_PARTIAL), the excess data is lost, and 
‘WSARecv genefales the error WSAEMSGSIZE. | 
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For connection-oriented sockets, WSARecv can indicate the graceful termination of the 


— virtual circuit in one of two ways that depend on whether the socket is byte stream or 


message oriented. For byte streams, zero bytes having been read (as indicated by a 
zero return value to indicate success, and joNumberOfBytesRecvd value of zero) 
indicates graceful closure and that no more bytes will ever be read. For message- 
oriented sockets, where a zero byte message is often allowable, a failure with an error 
code of WSAEDISCON is used to indicate graceful closure. In any case a return error 
code of WSAECONNRESET indicates an abortive close has occurred. 


The /pFlags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. That is, the semantics of this 
function are determined by the socket options and the /oFlags parameter. The latter is 
constructed by using the bitwise OR operator with any of the following values. 


Value Meaning 


MSG_PEEK Peeks at the incoming data. The data is copied into the buffer 


but is not removed from the input queue. This flag is valid only 
for nonoverlapped sockets. 


MSG_OOB Processes OOB data. (See section DECnet Out-Of-band data 
for a discussion of this topic.) 
MSG_PARTIAL This flag is for message-oriented sockets only. On output, 


indicates that the data supplied is a portion of the message 
transmitted by the sender. Remaining portions of the message 
will be supplied in subsequent receive operations. A subsequent 
receive operation with MSG_PARTIAL flag cleared indicates end 
of sender’s message. 


As an input parameter, this flag indicates that the receive 
operation should complete even if only part of a message has 
been received by the service provider. 


For message-oriented sockets, the MSG_PARTIAL bit is set in the /oFlags parameter if a 
partial message is received. If a complete message is received, MSG_PARTIAL is 
Cleared in /pFlags. In the case of delayed completion, the value pointed to by /pFiags is 


not updated. When completion has been indicated, the application should call 
-WSAGetOverlappedResult and examine the flags indicated by the /pdwFlags 


parameter. 


Overlapped socket I/O 


lf an overlapped operation completes immediately, WSARecv returns a value of zero 
and the |popNumberOfBytesRecvd parameter is updated with the number of bytes received 
and the flag bits indicated by the /pFlags parameter are also updated. If the overlapped 
operation is successfully initiated and will complete later, WSARecv returns — 
SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
loNumberOfBytesRecvd and I|pFlags are not updated. When the overlapped operation 
completes, the amount of data transferred is indicated either through the cbTransferred 
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parameter in the completion routine (if specified), or through the /ocbTransfer parameter 
in WSAGetOverlappedResult. Flag values are obtained by examining the /odwFlags 
parameter of WSAGetOverlappedResult. 


The WSARecv function can be called from within the completion routine of a previous 
WSARecv, WSARecvFrom, WSASend or WSASendTo function. For a given socket, 
1/O completion routines will not be nested. For a given socket, I/O completion routines 
will not be nested. This permits time-sensitive data transmissions to occur entirely within 
‘a preemptive context. 


The /oOverlapped parameter must be valid for the duration of the overlapped operation. 
_If multiple I/O operations are simultaneously outstanding, each must rerenes a 
separate WSAOVERLAPPED structure. 


If the /oCompletionRoutine parameter is NULL, the hEvent parameter of /oOverlapped is 
signaled when the overlapped operation completes if it contains a valid event object 
handle. An application can use WSAWaitForMultipleEvents or 
WSAGetOverlappedResult to wait or poll on the event object. 


If JoCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used 
by the application to pass context information to the completion routine. A caller that 
passes a non-NULL /pCompletionRoutine and later calls WSAGetOverlappedResult for 
the same overlapped I/O request may not set the fWait parameter for that invocation of 
WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is 
undefined, and attempting to wait on the hEvent perametel would produce unpredictable 
results. 


The completion routine follows the same rules as stipulated for Win32 file I/O completion 
routines. The completion routine will not be invoked until the thread is in an alertable wait 
state such as can occur when the function Pere oneull peeeMs with the 
fAlertable parameter set to TRUE is invoked. 


The transport providers allow an application to invoke send and receive Speraions from 
within the context of the socket I/O completion routine, and guarantee that, for a given 

- socket, I/O completion routines will not be nested. This permits time-sensitive data 
transmissions to occur entirely within a preemptive context. 


The prototype of the completion routine is as follows: 


CompletionRoutine is a placeholder for an application-defined or library-defined 
function name. The dwError specifies the completion status for the overlapped operation 
as indicated by IpOverlapped. The cbTransterred parameter specifies the number of 
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bytes received. The dwFlags parameter contains information that would have appeared 
in /pFlags if the receive operation had completed immediately. This function does not 
return a value. 
Returning from this function allows invocation of another pending completion routine for — 
this socket. When using WSAWaitForMultipleEvents, all waiting completion routines 
are called before the alertable thread’s wait is satisfied with a return code of 
WSA_IO_COMPLETION. The completion routines can be called in any order, not 
necessarily in the same order the overlapped operations are completed. However, the 
posted buffers are guaranteed to be filled in the same order in which they are supplied. 
Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
Windows Sockets Programming Considerations Overview, Microsoft Windows- -Specific 
Extension Functions, WSACloseEvent, WSACreateEvent, 
WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents 
WSARecvDisconnect 


The Windows Sockets WSARecvDisconnect function terminates reception on a socket, 
and retrieves the disconnect data if the socket is connection oriented. 


Parameters 
Ss 
[in] Descriptor identifying a socket. 


lolnboundDisconnectData 
lout] Pointer to the incoming disconnect data. 


Return Values | | | 

lf no error occurs, WSARecvDisconnect returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, anda ppc error code can be retrieved py een 
ee eset Ol: 
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Error code Meaning 
WSANOTINITIALISED A successful WSAStartup call must occur r before using 
| this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEFAULT The buffer referenced by the parameter 
lpInboundDisconnectData is too small. 

WSAENOPROTOOPT The disconnect data is not supported by the indicated 

| protocol family. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 

WSAENOTCONN The socket is not connected (connection-oriented 
sockets only). 

WSAENOTSOCK The descriptor is not a socket. 

Remarks 


The WSARecvDisconnect function is used on connection-oriented sockets to disable 
reception and retrieve any incoming disconnect data from the remote party. This is 
equivalent to a shutdown (SD_RECV), except that WSASendDisconnect also allows 
receipt of disconnect data (in protocols that support it). 


After this function has been successfully issued, subsequent receives on the socket will 
be disallowed. Calling WSARecvDisconnect has no effect on the lower protocol layers. 
For TCP sockets, if there is still data queued on the socket waiting to be received, or 
data arrives subsequently, the connection is reset, since the data cannot be delivered to — 
_the user. For UDP, incoming datagrams are accepted and queued. In no case will an 
ICMP error packet be generated. | 


To successfully receive incoming disconnect data, an application must use other 
mechanisms to determine that the circuit has been closed. For example, an application 
needs to receive an FD_CLOSE notification, to receive a zero return value, or to receive 
a WSAEDISCON or WSAECONNRESET error code from recv/WSARecv. 


The WSARecvDisconnect function does not close the socket, and resources attached 
to the socket will not be freed until closesocket is invoked. 


The WSARecvDisconnect function does not block regardless of the SO_LLINGER: 
setting on the socket. 


_ An application should not rely on being able to reuse a socket after it has been 
disconnected using WSARecvDisconnect. In particular, a Windows Sockets provider is 
not required to support the use of connect/WSAConnect on such a socket. 
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If no error occurs, WSARecvEx returns the number of bytes received. If the connection 
has been closed, it returns zero. Additionally, if a partial message was received, the 
MSG_PARTIAL bit is set in the flags parameter. If a complete message was ico: 
MSG_PARTIAL is not set in flags. 


Otherwise, a value of SOCKET ERROR is returned, and a specific error code can be 
retrieved by calling WSAGetLastError. 


Important For a stream oriented-transport protocol, MSG_PARTIAL is never set on 
return from WSARecvEx. This function behaves identically to the WINCOWS Sockets recv 
function for stream-transport protocols. 


Error code 


WSANOTINITIALISED 


WSAENETDOWN 
WSAEFAULT 


WSAENOTCONN 
WSAEINTR 


~WSAEINPROGRESS 
WSAENETRESET 


WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


-WSAEWOULDBLOCK 


~ WSAEINVAL 


Meaning 


_ A successful WSAStartup call must occur before using 


this function. 
The network subsystem has failed. 


The buf parameter is not completely contained in a valid 
part of the user address space. 


The socket is not. connected. 

The (blocking) call was canceled through 
WSACancelBlockingCall. 

A blocking Windows Sockets 1.1 call is in progress, or 
the service provider is still processing a callback function. 
The connection has been broken due to the remote host 
resetting. 


The descriptor is not a socket. 


MSG_OOB was specified, but the socket is not stream- 
style such as type SOCK_STREAM, OOB data is not 
supported in the communication domain associated with 
this socket, or the socket is unidirectional and supports 
only send operations. 


The socket has been shut down; it is not possible to use 
WSARecvEx on a socket after shutdown has been 
invoked with how set to SD__ RECEIVE or SD_BOTH. 


The socket is marked as nonblocking ¢ and the receive 


- operation would block. 
The socket has not been bound with bind, or an 


unknown flag was specified, or MSG_OOB was specified 
for a socket with SO_ OOBINLINE enabled or (for byte 
stream sockets only) len was zero or negative. 


(continued) | 


336 Volume 1. Winsock and QOS 


(continued) 

Error code Meaning 

WSAECONNABORTED _ The virtual circuit was terminated due to a time-out or 
other failure. The application should close the socket as it 
is no longer usable. | 

WSAETIMEDOUT The connection has been dropped because of a network 
failure or because the peer system failed to respond. 

WSAECONNRESET The virtual circuit was reset by the remote side executing 
a hard or abortive close. The application should close the 
socket as it is no longer usable. On a UPD-datagram 
socket this error would indicate that a previous send 
operation resulted in an ICMP “Port Unreachable” 
message. | 

Remarks 


The WSARecvEx function that is part of the Microsoft implementation of Windows 
Sockets 2 is similar to the more common recv function except that the flags parameter is 
an in-out parameter, not just an in parameter. The additional out parameter is used to 
indicate whether a partial or complete message is received when a message-oriented 
protocol is being used. 


The WSARecvEx and recv function identically for stream-oriented protocols. 


Making the flags parameter an in-out parameter accommodates two common situations 
in which a partial message will be received: 


e When the application’s data buffer size is smaller than the message size and the 
message coincidentally arrives in two pieces. 


e When the message is rather large and must arrive in several pieces. © 


The MSG_PARTIAL bit is set in the flags parameter on return from WSARecvEx when a 
partial message was received. If a complete message was received, MSG_PARTIAL is 
not set in flags. 


The Windows Sockets recv function is different than WSARecvEx in that the recv 
function always receives a single message for each call for message-oriented transport 
protocols. The recv function does not have a means to indicate to the application that 
the data received is only a partial message. An application must build its own protocol for 
checking whether a message is partial or complete by checking for the error code 
WSAEMSGSIZE after each call to recv. When the application buffer is smaller than the 
data being sent, as much of the message as will fit is copied into the user’s buffer and 
recv returns with the error code WSAEMSGSIZE. A subsequent call to recv will get the 
next part of the message. 
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Applications written for message-oriented transport protocols should be coded for this 
possibility if message sizing is not guaranteed by the application’s data transfer protocol. 
An application can use recv and manage the protocol itself. Alternatively, an application 
can use WSARecvEx and check that the MSG_PARTIAL bit is set in the flags | 
parameter. 


The WSARecvEx function provides the developer with a more effective way of checking 
whether a message received is partial or complete when a very large message arrives 
incrementally. For example, if an application sends a one-megabyte message, the 
transport protocol must break up the message in order to send it over the physical 
network. It is theoretically possible for the transport protocol on the receiving side to 
buffer all the data in the message, but this would be quite expensive in terms of 
resources. Instead, WSARecvEx can be used, minimizing overhead and eliminating the 
need for an application-based protocol. 


Version: Requires Windows Sockets 1.1. A Microsoft-specific extension. Not supported 
on Windows 95. 

Header: Declared in Mswsock.h. 

Library: Use Mswsock.lib. — 


recvfrom, select, send, socket, WSAAsyncSelect 


WSARecvFrom 


The Windows Sockets WSARecvFrom function receives a datagram and stores the 
source address. 


Parameters 
S 


in] Descriptor identifying a socket. 
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loBuffers 
[in/out] Pointer to an array of WSABUF structures. Each WSABUF structure contains 
a pointer to a buffer and the length of the buffer. 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesRecvd 
[out] Pointer to the number of bytes received by this call if the recv operation 
completes immediately. | 

IpFlags 
[in/out] Pointer to flags. 

loFrom 
[out] Optional pointer to a buffer that will hold the source address upon the completion 
of the overlapped operation. 


loFromlen 
[in/out] Pointer to the size of the from buffer, required only if /oFrom is specified. 


lpOverlapped 
[in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets). 


loCompletionRoutine 
[in] Pointer to the completion routine called when the recv operation has been 
completed (ignored for nonoverlapped sockets). 


Return Values 

If no error occurs and the receive operation has completed immediately, WSARecvFrom 
returns zero. In this case, the completion routine will have already been scheduled to be 
called once the calling thread is in the alertable state. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped 
operation has been successfully initiated and that completion will be indicated at a later 
time. Any other error code indicates that the overlapped operation was not successfully 
initiated and no completion indication will occur. | | 


Error code Meaning 


WSANOTINITIALISED _ A successful WSAStartup call must occur before using this function. 
WSAENETDOWN The network subsystem has failed. 
WSAEFAULT _- The /pBuffers, lpFlags, |pFrom, hie ede loFromlen, 


lpOverlapped, or [pCompletionRoutine argument is not totally 
contained in a valid part of the user address space: the /oFrom buffer 
was too small to accommodate the peer address. 


WSAEINTR | A blocking Windows Socket 1.1 call was canceled through 


WSACancelBlockingCall. 


WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the service 


provider is still processing a callback function. 


Error code 


WSAEINVAL 
WSAEISCONN 


WSAENETRESET 


WSAENOTCONN 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK | 


WSAEMSGSIZE 


WSAECONNRESET 


WSAEDISCON 
WSA_IO_PENDING 


WSA_OPERATION.. 
ABORTED 


- Remarks 
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Meaning 


The socket has not been bound (with bind, for example). 


The socket is connected. This function is not permitted with a 
connected socket, whether the socket is connection-oriented or 
connectionless. 


The connection has been broken due to keep-alive activity detecting a 
failure while the operation was in progress. 

The socket is not connected (connection-oriented sockets only). 
MSG_OOB was specified, but the socket is not stream-style such as 
type SOCK_STREAM, OOB data is not supported in the 
communication domain associated with this socket, or the socket is 
unidirectional and supports only send operations. 

The socket has been shut down; it is not possible to WSARecvFrom 
on a socket after shutdown has been invoked with how set to 
SD_RECEIVE or SD_BOTH. 


~ QOverlapped sockets: There are too many outstanding overlapped I/O 


requests. Nonoverlapped sockets: The socket is marked as 
nonblocking and the receive operation cannot be completed 
immediately. 


The message was too large to fit into the specified buffer and (for 


unreliable protocols only) any trailing portion of the message that did 


not fit into the buffer has been discarded. 


The virtual circuit was reset by the remote side executing a hard or 
abortive close. The application should close the socket as it is no 
longer useable. On a UPD-datagram socket this error would indicate 
that a previous send operation resulted in an ICMP “Port Unreachable” 


message. 


Socket s is message oriented and the virtual circuit was gracefully 
closed by the remote side. 

An overlapped operation was successfully initiated and completion will 
be indicated at a later time. © 


The overlapped operation has been canceled due to the closure of the 
socket. 


The WSARecvF rom function provides functionality over ag above the standard 
recvfrom function in three important areas: 


e |tcan be used in conjunction with overlapped sockets to perform overlapped receive 


operations. 


e |t allows multiple receive buffers to be specie” making it eppiicanie tc to the 
scatter/gather type of I/O. | 
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e The /pFlags parameter is both an input and an output parameter, allowing applications 
to sense the output state of the MSG_PARTIAL flag bit. Note however, that the 
MSG_PARTIAL flag bit is not supported by all protocols. 


The WSARecvFrom function is used primarily on a connectionless socket specified by 
s. The socket’s local address must be known. For server applications, this is usually 
done explicitly through bind. Explicit binding is discouraged for client applications. For 
client applications using this function the socket can become bound implicitly to a local 
address through sendto, WSASendTo, or WSAJoinLeaf. 


For overlapped sockets, this function is used to post one or more buffers into which 
incoming data will be placed as it becomes available on a (possibly connected) socket, 
after which the application-specified completion indication (invocation of the completion 
routine or setting of an event object) occurs. If the operation does not complete 
immediately, the final completion status is retrieved through the completion routine or 
WSAGetOverlappedResult. Also, the values indicated by /pFrom and IpFromlen are not 
updated until completion is itself indicated. Applications must not use or disturb these 
values until they have been updated, therefore the application must not use automatic 
(that is, stack-based) variables for these parameters. 


If both IpOverlapped and loCompletionRoutine are NULL, the socket in this function will 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the blocking semantics are identical to that of the standard 
WSARecv function and the jpOverlapped and |pCompletionRoutine parameters are 
ignored. Any data that has already been received and buffered by the transport will be 
copied into the supplied user buffers. For the case of a blocking socket with no data 
currently having been received and buffered by the transport, the call will block until data 
is received. 


The supplied buffers are filled in the order in which they appear in the array indicated by 
lpBuffers, and the buffers are packed so that no holes are created. 


The array of WSABUF structures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider's 
responsibility to capture these WSABUF structures before returning from this call. This 
enables applications to build stack-based WSABUF arrays. 


For connectionless socket types, the address from which the data originated is copied to 
the buffer indicated by /pFrom. The value pointed to by /pFromien is initialized to the size 
of this buffer, and is modified on completion to indicate the actual size of the address 
stored there. As noted previously for overlapped sockets, the joFrom and /pFromlen 
parameters are not updated until after the overlapped I/O has completed. The memory 
pointed to by these parameters must, therefore, remain available to the service provider 
‘and cannot be allocated on the application’s stack frame. The /pFrom and /|pFromlen 
parameters are ignored for connection-oriented sockets. 


For byte stream-style sockets (for example, type SOCK_STREAM), incoming data is 
placed into the buffers until: 
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e The buffers are filled. 
e The connection ts closed. 
e The internally buffered data is exhausted. 


Regardless of whether or not the incoming data fills all the buffers, the completion 
indication occurs for overlapped sockets. For message-oriented sockets, an incoming 
message is placed into the supplied buffers up to the total size of the buffers supplied, 
and the completion indication occurs for overlapped sockets. If the message is larger 
than the buffers supplied, the buffers are filled with the first part of the message. If the 
MSG_PARTIAL feature is supported by the underlying service provider, the 
MSG_PARTIAL flag is set in JoFlags and subsequent receive operation(s) will retrieve 
the rest of the message. If MSG_PARTIAL is not supported but the protocol is reliable, 
WSARecvFrom generates the error WSAEMSGSIZE and a subsequent receive 
operation with a larger buffer can be used to retrieve the entire message. Otherwise, 
(that is, the protocol is unreliable and does not support MSG_PARTIAL), the excess data 
is lost, and WSARecvFrom generates the error WSAEMSGSIZE. 


The /pFlags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. That is, the semantics of this 
function are determined by the socket options and the /pFlags parameter. The latter is 
constructed by using the bitwise OR operator with any of any of the following values. 


Value | Meaning 
MSG_PEEK _ Peeks at the incoming data. The data is copied into the buffer but is not 
removed from the input queue. This flag is valid only for Pee eae 
sockets. 
MSG_OOB Processes OOB data. (See DECnet Out-Of-band data for more 
| 3 information.) 
MSG_PARTIAL __ This flag is for message-oriented sockets only. On output, this flag indicates 


that the data supplied is a portion of the message transmitted by the 
sender. Remaining portions of the message will be supplied in subsequent 
receive operations. A subsequent receive operation with MSG_PARTIAL 
flag cleared indicates the end of the sender's message. | 

As an input parameter, this flag indicates that the receive operation should 
complete even if only part of a message has been received by the service 
provider. 


For message-oriented sockets, the MSG_PARTIAL bit is set in the /pFlags sail ifa 


partial message is received. If a complete message is received, MSG_PARTIAL is 
cleared in /pFlags. In the case of delayed completion, the value pointed to by /pFlags is 
not updated. When completion has been indicated the application should call 


| WSAGetOverlappedResult and examine the flags pointed to by the pawriags 


parameter. 


342 


Volume 1 Winsock and QOS | 


Overlapped Socket I/O 


lf an overlapped operation completes immediately, WSARecvFrom returns a value of 
zero and the JoNumberOfBytesRecvd parameter is updated with the number of bytes 
received and the flag bits pointed by the /pFlags parameter are also updated. If the 
overlapped operation is successfully initiated and will complete later, WSARecvFrom 
returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
loNumberOfBytesRecvd and IpFlags is not updated. When the overlapped operation 
completes the amount of data transferred is indicated either through the cbTransferred 
parameter in the completion routine (if specified), or through the /ocbTransfer parameter 
in WSAGetOverlappedResult. Flag values are obtained either through the dwFlags 
parameter of the completion routine, or by examining the (oaenaee parameter of 
WSAGetOverlappedResult. 


The WSARecvFrom function can be called from within the completion routine of a 
previous WSARecv, WSARecvFrom, WSASend, or WSASendTo function. For a given 
socket, I/O completion routines will not be nested. This permits time-sensitive data 
transmissions to occur entirely within a preemptive context. 


The /pOverlapped parameter must be valid for the duration of the overlapped operation. 
If multiple I/O operations are simultaneously outstanding, each must reference a 
separate WSAOVERLAPPED structure. 


If the |o>CompletionRoutine parameter is NULL, the hEvent parameter of jpOverlapped is 
signaled when the overlapped operation completes if it contains a valid event object 
handle. An application can use WSAWaitForMultipleEvents or 
WSAGetOverlappedResult to wait or poll on the event object. 


If joCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used 
by the application to pass context information to the completion routine. A caller that 
passes a non-NULL /oCompletionRoutine and later calls WSAGetOverlappedResult for 
the same overlapped I/O request may not set the fWait parameter for that invocation of 
WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is 
undefined, and attempting to wait on the hEvent parameter would produce unpredictable 
results. 


The completion routine follows the same rules as stipulated for Win32 file 1/O completion 
routines. The completion routine will not be invoked until the thread is in an alertable wait 
state such as can occur when the function WSAWaitForMultipleEvents with the 
fAlertable parameter set to TRUE is invoked. 


The transport providers allow an application to invoke send and receive aporione from 
within the context of the socket I/O completion routine, and guarantee that, for a given 
socket, I/O completion routines will not be nested. This permits time-sensitive data 
transmissions to occur entirely within a preemptive context. 


The prototype of the completion routine is on the following page. 
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he CompletionRoutine is a placeholder for an application-defined or library-defined 
unction name. The dwError specifies the completion status for the overlapped operation 
as indicated by /pOverlapped. The cbTransferred specifies the number of bytes received. 
The dwFlags parameter contains information that would have appeared in /pFlags if the 
receive operation had completed immediately. This function does not return a value. 


Returning from this function allows invocation of another pending completion routine for 
this socket. When using WSAWaitForMultipleEvents, all waiting completion routines 
are called before the alertable thread’s wait is satisfied with a return code of 
WSA_IO_COMPLETION. The completion routines can be called in any order, not 
necessarily in the same order the overlapped operations are completed. However, the 
posted buffers are guaranteed to be filled in the same order they are supplied. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSACloseEvent, WSACreateEvent, 
WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents | 


WSARemoveServiceClass 


The Windows Sockets WSARemoveServiceClass function permanently removes from 
the registry service class schema. | | < 


Parameters 
lpServiceClassld | | a 
in Pointer to the GUID for the service class you want to remove. 
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Return Values 


The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number can be retrieved by calling 
WSAGetLastError. : 


Error code | Meaning 

WSATYPE_NOT_FOUND The specified class was not found. 

WSAEACCES The calling routine does not have sufficient 
privileges to remove the Service. 

WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Sockets functions. 


WSAEINVAL The specified GUID was not valid. 
WSA NOT ENOUGH MEMORY There was insufficient memory to perform the 
operation 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


WSAResetEvent 


The Windows Sockets WSAResetEvent function resets the state of the specified event 
object to nonsignaled. 


Parameters 


hEvent 
[in] Handle that identifies an open event object handle. 


Return Values 


lf the WSAResetEvent function succeeds, the return value is TRUE. If the function fails, 
the return value is FALSE. To get extended error information, call WSAGetLastError. 
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Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before 
using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAEINPROGRESS. _ A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 

WSA_INVALID_HANDLE The hEvent parameter is not a valid event object 
handle. 

Remarks 

The WSAResetEvent function is used to set the state of the event object to 

nonsignaled. 


SERN 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
_ Extension Functions, WSACloseEvent, WSACreateEvent, WSASetEvent 


WSASend 


The Windows Sockets WSASend function sends data on a connected socket. 


Parameters 
S 


[in] Descriptor identifying a connected socket. 
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lpBuffers 
[in] Pointer to an array of WSABUF structures. Each WSABUF structure contains a 
pointer to a buffer and the length of the buffer. This array must remain valid for the 
duration of the send operation. | 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesSent 
[out] Pointer to the number of bytes sent by this call if the I/O operation completes 
immediately. 


dwFlags 
[in] Flags used to modify the behavior of the WSASend function call. See Using 
dwFlags in the Remarks section for more information. 


lpOverlapped 
[in] Pointer to a WSAOVERLAPPED structure. This parameter is ignored for 
nonoverlapped sockets. 


loCompletionRoutine 
[in] Pointer to the completion routine called when the send operation has been 
completed. This parameter is ignored for nonoverlapped sockets. 


Return Values 

If no error occurs and the send operation has completed immediately, WSASend returns 
zero. In this case, the completion routine will have already been scheduled to be called 
once the calling thread is in the alertable state. Otherwise, a value of SOCKET_ERROR 
is returned, and a specific error code can be retrieved by calling WSAGetLastError. The 
error code WSA_IO_PENDING indicates that the overlapped operation has been 
successfully initiated and that completion will be indicated at a later time. Any other error 
code indicates that the overlapped operation was not Suceeesrnly initiated and no 
completion indication will occur. 


Error code Meaning 


WSANOTINITIALISED A successful WSAStartup call must occur before using this function. 
WSAENETDOWN The network subsystem has failed. 
WSAEACCES The requested address is a broadcast address, but the appropriate 


flag was not set. 


WSAEINTR A blocking Windows Socket 1.1 call was canceled through 


WSACancelBlockingCall. 


WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the service 


provider is still processing a callback function. 


WSAEFAULT The /pBuffers, |lopNumberOfBytesSent, lpOverlapped, 


loCompletionRoutine argument is not les contained in a valid part 
of the user address space. 


Error code 


WSAENETRESET 


WSAENOBUFS 
WSAENOTCONN 
WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 
WSAEWOULDBLOCK 


WSAEMSGSIZE 


WSAEINVAL 


~ WSAECONNABORTED 


WSAECONNRESET 
WSA_IO_PENDING 


~ WSA_OPERATION_ 
ABORTED 


Remarks | 
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Meaning 

The connection has been broken due to keep-alive activity detecting 
a failure while the operation was in progress. 

The Windows Sockets provider reports a buffer deadlock. 

The socket is not connected. 

The descriptor is not a socket. 


MSG_OOB was specified, but the socket is not stream-style such as 
type SOCK_STREAM, OOB data is not supported in the 
communication domain associated with this socket, MSG_PARTIAL 


~ is not supported, or the socket is unidirectional and supports only 


receive operations. | 

The socket has been shut down; it is not possible to WSASend on a 
socket after shutdown has been invoked with how set to SD_SEND 
or SD_BOTH. 

Overlapped sockets: There are too many outstanding overlapped /O 
requests. Nonoverlapped sockets: The socket is marked as 
nonblocking and the send operation cannot be completed 
immediately. 

The socket is message oriented, and the message is larger than the 
maximum supported by the underlying transport. 

The socket has not been bound with bind or the socket is not 
created with the overlapped flag. 

The virtual circuit was terminated due to a time-out or other aide: 
The virtual circuit was reset by the remote side. 

An overlapped operation was SUPE oSSIHNy initiated and Eoipieion 
will be indicated at a later time. 

The overlapped operation has been canceled due to the closure of 
the socket, or the execution of the SIO_FLUSH command in 
WSAIlocti. 


The WSASend function provides functionality « over and above the standard send 
~ function in two important areas: 


e |Itcan be used in contention with overlapped sockets to perfor overlapped send 


operations. 


e |t allows multiple send buffers to be specified making it applicable to the scatter/gather 


type of I/O. 
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The WSASend function is used to write outgoing data from one or more buffers on a 
connection-oriented socket specified by s. It can also be used, however, on 
connectionless sockets that have a stipulated default peer address established through 


the connect or WSAConnect function. 


For overlapped sockets (created using WSASocket with flag 
WSA_FLAG_OVERLAPPED) sending information uses overlapped I/O, unless both 
lpOverlapped and lpCompletionRoutine are NULL. In that case, the socket is treated as 
a nonoverlapped socket. A completion indication will occur, invoking the completion of a 
routine or setting of an event object, when the supplied buffer(s) have been consumed 
by the transport. If the operation does not complete immediately, the final completion 
status is retrieved through the completion routine or WSAGetOverlappedResult. 


If both joOverlapped and /oCompletionRoutine are NULL, the socket in this function will 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the last two parameters (/oOverlapped, 
loCompletionRoutine) are ignored and WSASend adopts the same blocking semantics 
as send. Data is copied from the supplied buffer(s) into the transport’s buffer. If the 
socket is nonblocking and stream oriented, and there is not sufficient space in the 
transport’s buffer, WSASend will return with only part of the application’s buffers having 
been consumed. Given the same buffer situation and a blocking socket, WSASend will 
block until all of the application’s buffer contents have been consumed. 


The array of WSABUF structures pointed to by the /pBuffers parameter is transient. If 
this operation is completed in an overlapped manner, it is the service provider’s 
responsibility to capture these WSABUF structures before returning from this call. This 
enables applications to build stack-based WSABUF arrays. 


For message-oriented sockets, care must be taken not to exceed the maximum 
message size of the underlying provider, which can be obtained by getting the value of 
socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through 
the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. 


Note The successful completion of a WSASend does not indicate that the data was 
successfully delivered. 


Using dwFlags ; | 

The dwFlags parameter can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. That is, the semantics of this 
function are determined by the socket options and the dwFlags parameter. The latter is 
constructed by using the bitwise OR operator with any of any of the following values. 
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Value Meaning 
MSG_DONTROUTE Specifies that the data should not be subject to routing. A Windows 
| Sockets service provider can choose to ignore this flag. 
MSG_OOB Send OOB data on a stream-style socket such as SOCK_STREAM 
only. (See DECnet Out-Of-band data for a discussion of this topic.) 
MSG_PARTIAL Specifies that /JoBuffers only contains a partial message. Note that the 


error code WSAEOPNOTSUPP will be returned by transports that do 
not support partial message transmissions. 


Overlapped Socket I/O 


_If an overlapped operation completes immediately, WSASend retumne a value of zero 


and the JoNumberOfBytesSent parameter is updated with the number of bytes sent. If 
the overlapped operation is successfully initiated and will complete later, WSASend 

returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
loNumberOfBytesSent is not updated. When the overlapped operation completes the 


amount of data transferred is indicated either through the cbTransferred parameter in the 


completion routine (if specified), or through the /ocbTransfer parameter in 
WSAGetOverlappedResult. 


The WSASend function can be called from within the completion routine of a previous 
WSARecv, WSARecvFrom, WSASend, or WSASendTo function. This permits time- 
sensitive data transmissions to occur entirely within a preemptive context. 


The |pOverlapped parameter must be valid for the duration of the overlapped operation. 
lf multiple I/O operations are simultaneously outstanding, each must reference a 
separate WSAOVERLAPPED structure. | 


lf the JoCompletionRoutine parameter is NULL, the hEvent parameter of /oOverlapped is 
signaled when the overlapped operation completes if it contains a valid event object 
handle. An application can use WSAWaitForMultipleEvents or 
WSAGetOverlappedResult to wait or poll on the event object. 


If JoCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used 
by the application to pass context information to the completion routine. A caller that 
passes a non-NULL /pCompletionRoutine and later calls WSAGetOverlappedResult for | 
the same overlapped I/O request may not set the fWait parameter for that invocation of 
WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is 
undefined, and attempting to wait on the hEvent parameter would produce unpredictable 
results. 


The completion routine follows the same rules as stipulated for Win32 file I/O earpletion 


routines. The completion routine will not be invoked until the thread is in an alertable wait 
state such as can occur when the function WSAWaitForMultipleEvents with the 
fAlertable parameter set to TRUE is invoked. | : 
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The transport providers allow an application to invoke send and receive operations from 
within the context of the socket I/O completion routine, and guarantee that, for a given 
socket, I/O completion routines will not be nested. This permits time-sensitive data 
transmissions to occur entirely within a preemptive context. 


The prototype of the completion routine is as follows: 


The CompletionRoutine function is a placeholder for an application-defined or library- 
defined function name. The dwError parameter specifies the completion status for the 
overlapped operation as indicated by /pOverlapped. cbTransferred specifies the number 
of bytes sent. Currently there are no flag values defined and dwFlags will be zero. This 
function does not return a value. 


Returning from this function allows invocation of another pending completion routine for 
this socket. All waiting completion routines are called before the alertable thread’s wait is 
satisfied with a return code of WSA_IO_COMPLETION. The completion routines can be 
called in any order, not necessarily in the same order the overlapped operations are 
completed. However, the posted buffers are guaranteed to be sent in the same order 
they are supplied. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSACloseEvent, WSACreateE vent, | 
WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents 


WSASendDisconnect 


The Windows Sockets WSASendDisconnect function initiates termination of the 
connection for the socket and sends disconnect data. 
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Parameters 
Ss 

[in] Descriptor identifying a socket. 
|pOutboundDisconnectData 

[in] Pointer to the outgoing disconnect data. 


Return Values — | | 

If no error occurs, WSASendDisconnect returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
WSAGetLastError. 


Error code Meaning - 

WSANOTINITIALISED | A successful WSAStartup call must occur before 
using this function. 

WSAENETDOWN The network subsystem has failed. 

WSAENOPROTOOPT The parameter /oOutbounaDisconnectData is not — 


NULL, and the disconnect data is not supported by © 
the service provider. 


WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, 
or the service Pioviges | is still processing a callback 
3 | function. 
WSAENOTCONN _ The socket is not sonnected (connection-oriented 
as sockets only). 
WSAENOTSOCK 7 - The descriptor is not a socket. © 7 
WSAEFAULT The |pOutbounaDisconnectData parameter is not. 


completely contained in a valid part of the user 
address space. 


| Remarks | 7 

The WSASendDisconnect function i is used on connection-oriented sockets to disable 
transmission and to initiate termination of the connection along with the transmission of 
disconnect data, if any. This is equivalent to a shutdown (SD_SEND), except that 
WSASendDisconnect also allows sending disconnect data (in protocols that support it). 


After this function has been successfully issued, subsequent sends are disallowed. 


The /pOutboundDisconnectData parameter, if not NULL, points to a buffer containing the 
outgoing disconnect data to be sent to the remote Party | for relieve! by using 
~WSARecvDisconnect. | 


The WSASendDisconnect function does not close the socket, and resources attached 
to the socket will not be freed until closesocket | is invoked. 
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The WSASendDisconnect function does not block regardless of the SO_LINGER 


setting on the socket. 


An application should not rely on being able to reuse a socket after calling 


WSASendDisconnect. In particular, a Windows Sockets provider is not required to 


support the use of connect/WSAConnect on such a socket. 


Version: Requires Windows Sockets 2.0. 
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[in] Descr 


loBuffers 


[in] Pointer to an array of WSABUF structures. Each WSABUF structure contains a 
pointer to a buffer and the length of the buffer. This array must remain valid for the 


duration of the send operation. 


QwBufferCount 


[in] Number of WSABUF structures in the /oBuffers array. 
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IoNumberOfBytesSent 
[out] Pointer to the number of bytes sent by this call if the I/O operation completes 
immediately. 


dwFlags 

[in] Indicator specifying the way in which the call is made. 
loTo 

[in] Optional pointer to the address of the target socket. 
iToLen | 

[in] Size of the address in /pTo. 


IpOverlapped 
[in] A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets). 


loCompletionRoutine 
[in] Pointer to the completion routine called when the send operation has been 
completed (ignored for nonoverlapped sockets). 


Return Values 

If no error occurs and the send operation has completed immediately, WSASendTo 
returns zero. In this case, the completion routine will have already been scheduled to be 
called once the calling thread is in the alertable state. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code can be retrieved by calling 
WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped 
operation has been successfully initiated and that completion will be indicated at a later 
time. Any other error code indicates that the overlapped operation was not successfully 
initiated and no completion indication will occur. 


Error code Meaning | 

WSANOTINITIALISED A successful WSAStartup call must occur before using this _ 
function. 

WSAENETDOWN The network subsystem has failed. : | 

WSAEACCES | The requested address is a broadcast address, but the ‘ 
appropriate flag was not set. 

WSAEINTR A blocking Windows Socket 1.1 call was canceled through | 

: WSACancelBlockingCall. 
WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the service 
3 provider is still processing a callback function. 
WSAEFAULT sa The /pBuffers, IpTo, |pOverlapped, |pbNumberOfBytesSent, or 


loCompletionRoutine parameters are not part of the u user address 
space, or the /oTo argument is too small. 


WSAENETRESET | The connection has been broken due to keep-alive activity 
7 ae detecting a failure while the operation was in progress. 
WSAENOBUFS The Windows Sockets provider reports a buffer deadlock. 


(continued) 
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(continued) 
Error code Meaning 
WSAENOTCONN The socket is not connected (connection-oriented sockets only). 
WSAENOTSOCK The descriptor is not a socket. 
WSAEOPNOTSUPP MSG_OOB was specified, but the socket is not stream-style such 


as type SOCK_STREAM, OOB data is not supported in the 
communication domain associated with this socket, 
MSG_PARTIAL is not supported, or the socket is unidirectional 
and supports only receive operations. 

WSAESHUTDOWN The socket has been shut down; it is not possible to WSASendTo 
on a socket after shutdown has been invoked with how set to 

: SD_SEND or SD_BOTH. 

WSAEWOULDBLOCK ~ Overlapped sockets: there are too many outstanding overlapped 
I/O requests. Nonoverlapped sockets: The socket is marked as 
nonblocking and the send operation cannot be completed 


immediately. 

WSAEMSGSIZE The socket is message oriented, and the message is larger than 
the maximum supported by the underlying transport. 

WSAEINVAL The socket has not been bound with bind, or the socket is not 
created with the overlapped flag. 

WSAECONNABORTED The virtual circuit was terminated due to a time-out or other 
failure. 

WSAECONNRESET The virtual circuit was reset by the remote side. 

WSAEADDRNOTAVAIL The remote address is not a valid address (such as ADDR_ANY). 

WSAEAFNOSUPPORT Addresses in the specified family cannot be used with this socket. 

WSAEDESTADDRREQ A destination address is required. 

WSAENETUNREACH The network cannot be reached from this host at this time. 

WSA_IO_PENDING An overlapped operation was successfully initiated and 
completion will be indicated at a later time. 

WSA_OPERATION_ : The overlapped operation has been canceled due to the closure 

ABORTED | of the socket, or the execution of the SIO_ FLUSH command in | 
WSAloctl. 


Remarks 

The WSASendTo function provides eli over and above the standard sendto 

function in two important areas: 

e |tcan be used in eonyunenon with overlapped sockets to perform overlapped send 
operations. 


e |t allows multiple send buffers to be specified making it applicable to the scatter/gather 
type of I/O. 
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The WSASendTo function is normally used on a connectionless socket specified by s to 
send a datagram contained in one or more buffers to a specific peer socket identified by 
the JoTo parameter. Even if the connectionless socket has been previously connected 
using the connect function to a specific address, /oTo overrides the destination address 
for that particular datagram only. On a connection-oriented socket, the joTo and /ToLen 
parameters are ignored; in this case, the WSASendTo is equivalent to WSASend. 


For overlapped sockets (created using WSASocket with flag 
WSA_FLAG_OVERLAPPED) sending data uses overlapped I/O, unless both 
IpOverlapped and |pCompletionRoutine are NULL in which case the socket is treated as 
a nonoverlapped socket. A completion indication will occur (invoking the completion 
routine or setting of an event object) when the supplied buffer(s) have been consumed 
by the transport. If the operation does not complete immediately, the final completion 
status is retrieved through the completion routine or WSAGetOverlappedResult. 


If both IpOverlapped and |oCompletionRoutine are NULL, the socket in this function will 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the last two parameters (/pOverlapped, 
IoCompletionRoutine) are ignored and WSASendTo adopts the same blocking 
semantics as send. Data is copied from the supplied buffer(s) into the transport’s buffer. 
If the socket is nonblocking and stream oriented, and there is not sufficient space in the 
transport’s buffer, WSASendTo returns with only part of the application’s buffers having 
been consumed. Given the same buffer situation and a blocking socket, WSASendTo 
will block until all of the application’s buffer contents have been consumed. 


The array of WSABUF structures indicated by the /oBuffers parameter is transient. If this © 
operation is completed in an overlapped manner, it is the service provider’s responsibility 
to capture these WSABUF structures before returning from this call. This enables 
applications to build stack-based WSABUF arrays. 


For message-oriented sockets, care must be taken not to exceed the maximum 
message size of the underlying transport, which can be obtained by getting the value of 
socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through 
the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. 


The successful completion ofa WSASendTo does not indicate that the data was 
successfully delivered. 7 


The dwFlags parece can be used to influence the behavior of the function invocation 
beyond the options specified for the associated socket. That is, the semantics of this 
function are determined by the socket options and the dwFlags parameter. The latter is 
constructed by using the bitwise OR operator with any of any of the following values. 
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Value Meaning 


~MSG_DONTROUTE Specifies that the data should not be subject to routing. A 


Windows Socket service provider may choose to ignore 


this flag. | 

MSG_OOB -. Send OOB data (stream-style socket such as 
SOCK_STREAM only). 

MSG_PARTIAL Specifies that /oBuffers only contains a partial message. Note 


that the error code WSAEOPNOTSUPP will be returned by 
transports that do not support partial message transmissions. 


Overlapped Socket I/O 

If an overlapped operation completes imadiaiely: WSASendTo returns a value of zero 
and the JoNumberOfBytesSent parameter is updated with the number of bytes sent. If 
the overlapped operation is successfully initiated and will complete later, WSASendTo 
returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
loNumberOfBytesSent is not updated. When the overlapped operation completes the 
amount of data transferred is indicated either through the cbTransferred parameter in the 
completion routine (if specified), or through the /ocbTransfer parameter in 
WSAGetOverlappedResult. 


The WSASendTo function can be called from within the completion routine of a previous 
WSARecv, WSARecvFrom, WSASend, or WSASendTo function. This permits time- 
sensitive data transmissions to occur entirely within a preemptive context. 


The /pOverlapped parameter must be valid for the duration of the overlapped operation. 
If multiple I/O operations are simultaneously outstanding, each must reference a 
separate WSAOVERLAPPED structure. 


lf the /oCompletionRoutine parameter is NULL, the hEvent parameter of /oOverlapped is 
signaled when the overlapped operation completes if it contains a valid event object 
handle. An application can use WSAWaitForMultipleEvents or 
WSAGetOverlappedResult to wait or poll on the event object. 


lf JoOCompletionRoutine is not NULL, the hEvent parameter is ignored fia can be used 
by the application to pass context information to the completion routine. A caller that 
passes a non-NULL /pCompletionRoutine and later calls WSAGetOverlappedResult for 
the same overlapped I/O request may not set the fWait parameter for that invocation of 
WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is 
undefined, and attempting to wait on the hEvent parameter would eee unpredictable 
results. 


The completion routine follows the same rules as stipulated for Win32 file |/O completion 
routines. The completion routine will not be invoked until the thread is in an alertable wait 
state such as can occur when the function WSAWaitForMultipleEvents with the 
fAlertable parameter set to TRUE is invoked. 
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Transport providers allow an application to invoke send and receive operations from 
within the context of the socket I/O completion routine, and guarantee that, for a given 
socket, I/O completion routines will not be nested. This permits time-sensitive data 
transmissions to occur entirely within a preemptive context. 


The prototype of the completion routine is as follows: 


The CompletionRoutine function is a placeholder for an application-defined or library- 
defined function name. The dwError parameter specifies the completion status for the 
overlapped operation as indicated by IpOverlapped. The cbTransferred parameter 
specifies the number of bytes sent. Currently there are no flag values defined and 
dwFlags will be zero. This function does not return a value. 


Returning from this function allows invocation of another pending completion routine for 
this socket. All waiting completion routines are called before the alertable thread’s wait is 
satisfied with a return code of WSA_IO_COMPLETION. The completion routines can be 
called in any order, not necessarily in the same order in which the overlapped operations 
are completed. However, the posted buffers are guaranteed to be sent in the same order 
they are supplied. 


Version: epaquires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows: “Specific 
Extension Functions, WSACloseEvent, WSACreateEvent, 
WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents 


WSASetBlockingHook 
This function has been removed in compliance mp) the Windows Sockets 2 


specification, revision 2.2.0. 


The function is not exported directly by the Ws2_32.dll, and Windows Sockets 2 
applications should not use this function. Windows Sockets 1.1 applications that call this 
function are still supported through the Winsock.dll and Wsock32.dll. 
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Blocking hooks are generally used to keep a single-threaded GUI application responsive 
during calls to blocking functions. Instead of using blocking hooks, an application should 
use a separate thread (separate from the main GUI thread) for network activity. 


WSASetEvent | 


The Windows Sockets WSASetEvent function sets the state of the specified event 
object to signaled. | | | 


Parameters 


hEvent 
[in] Handle that identifies an open event object. 


Return Values 
If the function succeeds, the return value is TRUE. 


If the function fails, the return value is FALSE. To get extended error information, call 


WSAGetLastError. 
Error code Meaning a 
WSANOTINITIALISED A successful WSAStartup call must occur before 
| | using this function. 
WSAENETDOWN The network subsystem has failed. © 
WSAEINPROGRESS | A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 
WSA_INVALID_ HANDLE The hEvent parameter is not a valid event object 
| ss | — handle. | 
Remarks 


The WSASetEvent function sets the state of the event object to be signaled. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 
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Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSACloseEvent, WSACreateEvent, WSAResetEvent 


WSASetLastError 


The Windows Sockets WSASetLastError function sets the error code that can be 
retrieved through the WSAGetLastError function. 


Parameters 


/Error 
[in] Integer that specifies the error code to be returned by a subsequent 
WSAGetLastError call. 


Return Values 
This function generates no return values. 


- Error code Meaning 


WSANOTINITIALISED A successful WSAStartup call must occur before | 
| - using this function. 


Remarks 


The WSASetLastError function allows an application to set the error code to Ba 
returned by a subsequent WSAGetLastError call for the current thread. Note that any 
subsequent Windows Sockets routine called by the application will override the error 
code as set by this routine. 


The error code set by WSASetLastError is different from the error code reset by calling 
the function getsockopt with SO_ERROR. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows- “Specific | 
Extension Functions, getsockopt, WSAGetLastError 
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WSASetService 


The Windows Sockets WSASetService function registers or removes from the registry a 
service instance within one or more name spaces. This function can be used to affect a 
specific name space provider, all providers associated with a specific name space, or all 
providers across all name spaces. 


Parameters 
lpqsRegInfo 
[in] Pointer to the service information for registration or deregistration. 
essOperation 
[in] Enumeration whose values include the following. 
Value Description 
RNRSERVICE_REGISTER Register the service. For SAP, this means sending out a 


periodic broadcast. This is an NOP for the DNS name space. 
For persistent data stores, this means updating the address 
information. 


RNRSERVICE_DEREGISTER Remove the service from the registry. For SAP, this means 
stop sending out the periodic broadcast. This is an NOP for 
the DNS name space. For persistent data stores this means 
deleting address information. 


RNRSERVICE_DELETE Delete the service from dynamic name and persistent spaces. 
For services represented by multiple CSADDR_INFO 
structures (using the SERVICE_MULLTIPLE flag), only the 
supplied address will be deleted, and this must match exactly 
the corresponding CSADDR_INFO structure that was 
supplied when the service was registered. 


dwControlFlags . 
[in] Meaning of dwContro/Flags is dependent on the following values. 
Flag Meaning 
SERVICE MULTIPLE Controls scope of operation. When clear, service addresses are 


managed as a group. A register or removal from the registry 
invalidates all existing addresses before adding the given address set. 
When set, the action is only performed on the given address set. A 
register does not invalidate existing addresses and a removal from 
the registry only invalidates the given set of addresses. — 


Chapter 8 Winsock 2 Functions 361 


The available values for essOperation and dwControlFlags combine to give meanings as 
shown in the following table. 


Operation Flags Service already exists Service does not exist 
RNRSERVICE _ None Overwrites the object. Uses only Creates a new object. 
REGISTER addresses specified. Object is Uses only addresses 
| REGISTERED. specified. Object is 
| REGISTERED. 
RNRSERVICE_ SERVICE _ Update object. Adds new Creates a new object. 
REGISTER MULTIPLE addresses to existing set. Object Uses all addresses 
is REGISTERED. specified. Object is 
: REGISTERED. 
RNRSERVICE_ None — Removes all addresses, but WSASERVICE _ 
DEREGISTER does not remove object from NOT_FOUND 


name space. Object is removed 
from the registry. | 


RNRSERVICE_ SERVICE _ Updates object. Removes only WSASERVICE_ 
DEREGISTER MULTIPLE — addresses that are specified. NOT_FOUND 
Only marks object as 
DEREGISTERED if no 
addresses present. Does not 
remove from the name space. 


RNRSERVICE_ None Removes object from the name §WSASERVICE_ 
DELETE space. NOT_FOUND ~ 
RNRSERVICE_ SERVICE_ Removes only addresses that WSASERVICE_ 
DELETE ‘MULTIPLE are specified. Only removes NOT_FOUND 


object from the name space if no 
addresses remain. 


Return Values 

The return value for WSASetService is zero if the operation was successful. Otherwise, 
the value SOCKET_ERROR is returned, and a specific error number can be retrieved by 
calling WSAGetLastError. 


Error code Meaning 
WSAEACCES The calling routine does not have sufficient privileges to install 
, | , the Service. | ie: 
- WSAEINVAL One or more required parameters were invalid or missing. 
WSANOTINITIALIZED The WiS2_32.dll has not been initialized. The application must — 
first call WSAStartup before calling any Windows Sockets 
functions. 


_ (continued) 
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(continued) 
Error code Meaning 
WSA NOT ENOUGH MEMORY There was insufficient memory to perform the operation. 
WSASERVICE NOT FOUND No such service is known. The service cannot be found in the 
specified name space. 
Remarks 


SERVICE_MULTIPLE lets an application manage its addresses independently. This is 
useful when the application wants to manage its protocols individually or when the 
service resides on more than one machine. For instance, when a service uses more than 
one protocol, it may find that one listening socket aborts but the others remain 
operational. In this case, the service could remove the aborted address from the registry 
without affecting the other addresses. 


When using SERVICE_MULTIPLE, an application must not let stale addresses remain in 
the object. This can happen if the application aborts without issuing a DEREGISTER 
request. When a service registers, it should store its addresses. On its next invocation, 
the service should explicitly remove these old stale addresses from the registry before 
registering new addresses. 


Service Properties 


The following table describes how service property data is represented in a 
WSAQUERYSET structure. Fields labeled as (Optional) can be supplied with a NULL 
pointer. 


WSAQUERYSET member name Service property description 


Field Name Service Property Description 

dwSize Must be set to sizeof (WSAQUERYSET). This is 

a versioning mechanism. 
dwOutputFlags Not applicable and ignored. 
LpszServicelnstanceName __ Referenced string contains the service instance 
| name. | | 
LpServiceClassld The GUID corresponding to this service class. 
LpVersion — | (Optional) Supplies service instance version 
| number. - 

LpszComment (Optional) An optional comment string. 
DwNameSpace See table that follows. 

LpNSProviderld | See table that follows. | 

| LpszContext | | (Optional) Specifies the starting point of the 


query in a hierarchical name space. 
DwNumberOfProtocols Ignored. 


Chapter 8 Winsock 2 Functions 


WSAQUERYSET member name Service property description 


LpafpProtocols Ignored. 
LpszQueryString Ignored. | 
DwNumberOfCsAddrs The number of elements in the array of 
SADDR_INFO structures referenced by 
lpcsaBufter. 
LpcsaBuffer | A pointer to an array of CSADDR_INFO | 


structures that contain the address(es) that the 
service is listening on. 


LpBlob (Optional) This is a pointer to a provider-specific 
entity. 


As illustrated in the following, the combination of the dwNameSpace and |pNSProviderld 
parameters determine that name space providers are affected by this function. 


DwNameSpace _ IpNSProviderld Scope of impact 

Ignored | Non-NULL ~—_—siTihe specified name-space provider. 
A valid name space _. NULL ~ : All name-space providers that 
identifier | | | support the indicated name space. 
NS_ALL | NULL | All name-space providers. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. | 
Library: Use Ws2_32.lib. 


Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


WSASocket 


The Windows Sockets WSASocket function creates a socket that is bound to a specific 
7 _ transport-service provider. | | 
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Parameters 
af 
[in] Address family specification. 
type 
[in] Type specification for the new socket. 
protocol 
[in] Protocol to be used with the socket that is specific to the indicated address family. 


IoProtocolinfo | 
[in] Pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of 
the socket to be created. 

g 
[in] Reserved. 


dwFlags 
[in] Flag that specifies the socket attribute. 


Return Values 


If no error occurs, WSASocket returns a descriptor referencing the new socket. 
Otherwise, a value of INVALID_ SOCKET is returned, and a specific error code can be 
retrieved by calling WSAGetLastError. 


Note This error code description is Microsoft-specific. 


Error code Meaning 

WSANOTINITIALISED A successful WSAStartup call must occur before using this 
function. 

WSAENETDOWN The network subsystem has failed. 

WSAEAFNOSUPPORT The specified address family is not supported. 

WSAEINPROGRESS A blocking Windows Sockets 1.1 call is in progress, or the 
service provider is still processing a callback function. 

WSAEMFILE | No more socket descriptors are available. 

WSAENOBUFS No buffer space is available. The socket cannot be created. 

WSAEPROTONOSUPPORT The specified protocol is not supported. 

WSAEPROTOTYPE _ The specified protocol is the wrong type for this socket. 


WSAESOCKTNOSUPPORT __ The specified socket type is not supported in this address family. 
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Error code Meaning 


WSAEINVAL This value is true for any of the following conditions. 

| e The parameter g specified is not valid. 

e The WSAPROTOCOL_INFO structure that /oProtocolinfo 
points to is incomplete, the contents are invalid or the 
WSAPROTOCOL_INFO structure has already been used in 
an earlier duplicate socket operation. | | 

e The values specified for members of the socket triple <af, 
type, and protocol> are nemeneny supported, but the given 

combination is not. 


WSAEFAULT | loProtocolinfo argument is not in a valid part of the PIGeeee 
, ; address space. 
WSAINVALIDPROVIDER The service provider returned a . version other than 2.2. | 
WSAINVALIDPROCTABLE The service provider returned an invalid or incomplete procedure 
table to the WSPStartup. 
Remarks 


The WSASocket function causes a socket descriptor and any related resources to be 
allocated and associated with a transport-service provider. By default, the socket will not 

have an overlapped attribute. If joProtocolinfo is NULL, the Ws2_32.dll uses the first 

_ three parameters (af, type, protocol) to determine which service provider is used by 
selecting the first transport provider able to support the stipulated address family, socket 
type, and protocol values. If the /pProtocolinfo is not NULL, the socket will be bound to 
the provider associated with the indicated WSAPROTOCOL_INFO structure. In this 
instance, the application can supply the manifest constant FROM_PROTOCOL_INFO as 
the value for any of af, type, or protocol. This indicates that the corresponding values 
from the indicated WSAPROTOCOL_INFO structure (iAddressFamily, iSocketType, 
iProtocol) are to be assumed. In any case, the values supplied for af, type, and protocol 
are supplied unmodified to the transport- service provider. 


When selecting a protocol and its supporting service provider based on af, type, and 
protocol, this procedure will only choose a base protocol or a protocol chain, not a 
protocol layer by itself. Unchained protocol layers are not considered to have partial 
matches on type or af, either. That is, they do not lead to an errorcode of. 
WSAEAFNOSUPPORT or WSAEPROTONOSUPPORT, if no suitable protocol is found. 


Note The manifest constant AF_ UNSPEC continues to be defined in the header file but 
_ its use Is strongly discouraged, « as this can cause ambiguity In interpreting the value of 
the pee eee , 


The dwFlags parameter can be used to specify the attributes of the socket by using the 
bitwise OR operator with any of the following flags. 
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Flag Meaning 

WSA_FLAG_ . | This flag causes an overlapped socket to be created. Overlapped 

OVERLAPPED | sockets can utilize WSASend, WSASendTo, WSARecv, 

| WSARecvFrom, and WSAloctl for overlapped I/O operations, 
which allow multiple operations to be initiated and in progress 
simultaneously. All functions that allow overlapped operation 
(WSASend, WSARecv, WSASendTo, WSARecvFrom, WSAloctl) 

also support nonoverlapped usage on an overlapped socket if the 
values for parameters related to overlapped operations are NULL. 

WSA_FLAG_ | Indicates that the socket created will be a c_root in a multipoint 


MULTIPOINT_C_ROOT session. Only allowed if a rooted control plane is indicated in the 


protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint 
and Multicast Semantics for additional information. 


WSA_FLAG_ Indicates that the socket created will be a c_leaf ina multicast 
MULTIPOINT_C_LEAF session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated 


in the protocol’s WSAPROTOCOL_INFO structure. Refer to 
Multipoint and Multicast Semantics for additional information. 


WSA_FLAG_ Indicates that the socket created will be a d_root in a multipoint 


MULTIPOINT_ D_ROOT session. Only allowed if a rooted data plane is indicated in the 


protocol’s WSAPROTOCOL_INFO structure. Refer to Multipoint 
and Multicast Semantics for additional information. 


WSA_FLAG_ _ | Indicates that the socket created will be a d_leaf in a multipoint 
MULTIPOINT_D_LEAF session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated 


in the protocols WSAPROTOCOL_INFO structure. Refer to — 
Multipoint and Multicast Semantics for additional information. 


— Important For multipoint sockets, exactly one of WSA_FLAG_MULTIPOINT_C_ROOT 


or WSA_FLAG_MULTIPOINT_C_LEAF must be specified, and exactly one of 
WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF must be 
specified. Refer to Multipoint and Multicast Semantics for additional information. 


Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, 


~-and must be in a connected state before any data can be sent or received on them. A 


connection to another socket is created with a connect/WSAConnect call. Once 
connected, data can be transferred using send/WSASend and recv/WSARecv calls. 
When a session has been completed, a closesocket must be performed. 


~The communications protocols used to implement a reliable, connection-oriented socket 


ensure that data is not lost or duplicated. If data for which the peer protocol has buffer - 
space cannot be successfully transmitted within a reasonable length of time, the 
connection is considered broken and subsequent calls will fail with the error code set to 
WSAETIMEDOUT. 
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Connectionless, message-oriented sockets allow sending and receiving of datagrams to 
and from arbitrary peers using sendto/WSASendTo and recvfrom/WSARecvFrom. If 
such a socket is connected to a specific peer, datagrams can be sent to that peer using 
send/WSASend and can be received from (only) this peer using recv/WSARecv. 


Support for sockets with type RAW is not required, but service providers are encouraged 
to support raw sockets whenever possible. 


Shared Sockets 
When a special WSAPROTOCOL_INFO structure (obtained through the 
WSADuplicateSocket function and used to create additional descriptors for a shared 
socket) is passed as an input parameter to WSASocket, the g and dwFlags 
parameters are ignored. Such a WSAPROTOCOL_INFO structure may ony be used 
once, otherwise the error code WSAEINVAL will result. 


Version: Requires Windows Sockets 2.0. 

Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. | 
Unicode: Implemented as Unicode and ANSI versions on all platforms. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, accept, bind, connect, getsockname, getsockopt, Oc lSOenes 
listen, recy, recvfrom, eplert Send, sendio, setsocKer!, shutdown 


WSAStartup 


The Windows Sockets WSAStartup function initiates use of Ws2_32.dll by a process. 


Parameters © 
7 wVersionRequested 
— [in] Highest version of Windows Sockets support that the caller can use. The high- 
order byte specifies the minor version (revision) number; the low-order byte specifies 
the major version number. 


lpoWSAData 


[out] Pointer to the WSADATA data structure that | is to receive details of the Windows 
Sockets implementation. 
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Return Values 


The WSAStartup function returns zero if successful. Otherwise, it returns one of the 
error codes listed in the following. 


An application cannot call WSAGetLastError to determine the error code as is normally 
done in Windows Sockets if WSAStartup fails. The Ws2_32.dll will not have been 
loaded in the case of a failure so the client data area where the last error information is 
stored could not be established. 


Error code Meaning 

WSASYSNOTREADY Indicates that the underlying network subsystem is 
| not ready for network communication. 

WSAVERNOTSUPPORTED The version of Windows Sockets support 


requested is not provided by this particular 
Windows Sockets implementation. 


WSAEINPROGRESS A blocking Windows Sockets 1.1 operation is in 
progress. | 
~WSAEPROCLIM Limit on the number of tasks supported by the 
- Windows Sockets implementation has been 
reached. | 
WSAEFAULT The |pWSADaia is not a valid pointer. 


Remarks 


The WSAStartup function must be the first Windows Sockets function called by an 
application or DLL. It allows an application or DLL to specify the version of Windows 
Sockets required and retrieve details of the specific Windows Sockets implementation. 
The application or DLL can only issue further Windows Sockets functions after 
successfully calling WSAStartup. 


In order to support future Windows Sockets implementations and applications that can 
have functionality differences from the current version of Windows Sockets, a negotiation 
takes place in WSAStartup. The caller of WSAStartup and the Ws2_32.dll indicate to 
each other the highest version that they can support, and each confirms that the other’s 
highest version is acceptable. Upon entry to WSAStartup, the Ws2_32.dll examines the 
version requested by the application. If this version is equal to or higher than the lowest 
version supported by the DLL, the call succeeds and the DLL returns in wHighVersion 
the highest version it supports and in wVersion the minimum of its high version and 
wVersionRequested. The Ws2_32.dll then assumes that the application will use 
wVersion. lf the wVersion parameter of the WSADATA structure is unacceptable to the 
caller, it should call WSACleanup and either search for another Ws2_32.dll or fail to 
initialize. 


~ It is legal and possible for an application written to this version of the specification to 


successfully negotiate a higher version number version. In that case, the application is 
only guaranteed access to higher-version functionality that fits within the syntax defined 
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in this version, such as new loctl codes and new behavior of existing functions. New 
functions may be inaccessible. To get full access to the new syntax of a future version, 
the application must fully conform to that future version, such as compiling against a new 
header file, linking to a new library, or other special cases. 


This negotiation allows both a Ws2_32.dll and a Windows Sockets application to support 
a range of Windows Sockets versions. An application can use Ws2_32.dll if there is any 
overlap in the version ranges. The following table shows how WSAStartup works with 
different applications and Ws2_32.dll versions. 


App DLL wVersion wHigh 

versions versions requested  wvVersion version End result 

1.1 i a 1.1 1.1 1.1 use 1.1 

1.0 1.1 1.0 1.1 1.0 1.0 use 1.0 

1.0 1.01.1 1.0 1.0 1.10 use 1.0 

1.1 1.0 1.1 1.1 1.1 1.1 use 1.1 

1.1 1.0 1.1. 1.0 1.0 Application fails 

1.0 1.1 1.0 --- nem WSAVERNOT 
UPPORTED 

1.0 1.1 1.0 1.1 1.1 1.1 1.1 use 1.1 

1.1 2.0 1.1 2.0 1.1 1.1 use 1.1 

2.0 2.0 — 2.0 en 2i0 2.0 use 2.0 

Example 


The following code fragment demonstrates how an application that supports only 
version 2.2 of Windows Sockets makes a WSAStartup call: 


(continued) 
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(continued) 


Once an application or DLL has made a successful WSAStartup call, it can proceed to 
make other Windows Sockets calls as needed. When it has finished using the services 
of the Ws2_32.dll, the application or DLL must call WSACleanup to allow the 
Ws2_32.dll to free any resources for the application. 


Details of the actual Windows Sockets implementation are described in the WSADATA 
structure. 


An application or DLL can call WSAStartup more than once if it needs to obtain the 
WSADATA structure information more than once. On each such call the application can 
specify any version number supported by the DLL. 


An application must call one WSACleanup call for every successful WSAStartup call to 
allow third-party DLLs to make use of a Ws2_32.dll on behalf of an application. This 
means, for example, that if an application calls WSAStartup three times, it must call 
WSACleanup three times. The first two calls to WSACleanup do nothing except 
decrement an internal counter; the final WSACleanup call for the task does all 
necessary resource deallocation for the task. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. ee ee 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, send, sendto, WSACleanup | : 
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WSAStringToAddress 


The Windows Sockets WSAStringToAddress function converts a numeric string to a 
SOCKADDR structure, suitable for passing to Windows Sockets routines that take such 


a structure. 


Parameters 


AddressSiring | 
[in] Pointer to the zero-terminated human-readable numeric string to convert. 


AddressFamily 
[in] Address family to which the string belongs. 


lpProtocolinfo 
[in] (optional) The WSAPROTOCOL_INFO structure associated with the provider to 
be used. If this is NULL, the call is routed to the provider of the first protocol 
supporting the indicated AddressFamily. 


lpAddress | 
out] Buffer that is filled with a single SOCKADDR. 


lpAddressLength | 
[in/out] Length of the Address buffer. Returns the size of the resultant SOCKADDR 


structure. If the supplied buffer is not large enough, the function fails with a specific 
error of WSAEFAULT and this parameter is updated with the required size in bytes. 


Return Values 


The return value for WSAStringToAddress is Zero if the operation was successful. 
Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be 
retrieved by calling WSAGetLastError. | | 


Error code | _ Meaning 
WSAEFAULT | The specified Address buffer is too small. Passes 
eee in alarger buffer. — ee eee 
WSAEINVAL Unable to translate the string into a SOCKADDR. 
| | : See the following Remarks section for more - 
information. - | | 


continued 
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(continued) 
Error code Meaning 
WSANOTINITIALIZED The Ws2_32.dll has not been initialized. The 


application must first call WSAStartup before 
calling any Windows Socket functions. 


WSA NOT ENOUGH MEMORY There was insufficient memory to perform the 
operation. 


Remarks 


The WSAStringToAddress function converts alphanumeric address to SOCKADDR 
structures. WSAStringToAddress is the protocol independent equivalent of the BSD 
inet_ntoa function. 


Any missing components of the address will be defaulted to a reasonable value, if 


_ possible. For example, a missing port number will default to zero. If the caller wants the 


translation to be done by a particular provider, it should supply the corresponding 
WSAPROTOCOL_INFO structure in the /pProtocollnfo parameter. 


The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family 
member of the SOCKADDF_IN structure, which is passed in the Pog parameter in 
the form of a SOCKADDR siructure, is not set to AF_INET. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 

Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000. 


WSAUnhookBlockingHook 


This function has been removed in compliance with the Windows Sockets 2 
specification, revision 2.2.0. 


The function is not exported directly by the Ws2_32.dll, and Windows Sockets 2 
applications should not use this function. Windows Sockets 1.1 applications that call this 
function are still supported through the Winsock.dll and Wsock32.dll. 


_ Blocking hooks are generally used to keep a single-threaded GUI application responsive 


during calls to blocking functions. Instead of using blocking hooks, an application should 
use a separate thread (separate from the main GUI thread) for network activity. 
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WSAWaitForMultipleEvents 


The Windows Sockets WSAWaitForMultipleEvents function returns either when one or 
all of the specified event objects are in the signaled state, or when the time-out interval 


expires. 


Parameters 


cEvents | 
[in] Indicator specifying the number of event object handles in the array pointed to by 
IohEvents. The maximum number of event object handles is 
WSA_MAXIMUM_WAIT_EVENTS. One or more events must be specified. 


lphEvents 
in] Pointer to an array of event object handles. 


fWaitAll 
[in] Indicator specifying the wait type. If TRUE, the function returns when all event 
objects in the /ohEvents array are signaled at the same time. If FALSE, the function 
returns when any one of the event objects is signaled. In the latter case, the return 
value indicates the event object whose state caused the function to return. 


dwTimeout 
[in] Indicator specifying the time-out interval, in milliseconds. The function returns if 
the interval expires, even if conditions specified by the fWaitAl/ parameter are not 
satisfied. If dwTimeout is zero, the function tests the state of the specified event 
objects and returns immediately. If dw7imeout is WSA_INFINITE, the function’s time- 
out interval never expires. 


fAlertable | | : | 
_ [in] Indicator specifying whether the function returns when the system queues an I/O — 
completion routine for execution by the calling thread. If TRUE, the completion routine 
is executed and the function returns. If FALSE, the completion routine is not executed 
when the function returns. | | 


Return Values -— | 


If the WSAWaitForMultipleEvents function succeeds, the return value indicates the 
event object that caused the function to return. 


If the function fails, the return value is WSA_WAIT_FAILED. To get extended error 
information, call WSAGetLastError. 
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The return value upon success is one of the following values. 


Value 


WSA_WAIT_EVENT_0O to 
(WSA_WAIT_EVENT_0O + cEvents - 1) 


WAIT_IO_COMPLETION — 
WSA_WAIT TIMEOUT — 

Error code 
WSANOTINITIALISED 
WSAENETDOWN 
WSAEINPROGRESS 
WSA_NOT_ ENOUGH. MEMORY 
WSA_INVALID_ HANDLE 


WSA_INVALID_PARAMETER 


Remarks 


Meaning 


If fWaitAll is TRUE, the return value indicates that the 
state of all specified event objects is signaled. If 
fWaitAll is FALSE, the return value minus 
WSA_WAIT_EVENT_O indicates the /ohEvents array 
index of the object that satisfied the wait. 

One or more I/O completion routines are queued for 
execution. 

The time-out interval Sinpacd: and the conditions 
specified by the fWaitAl/ parameter are not satisfied. 


Meaning 


A successful WSAStartup call must occur before 
using this function. 


The network subsystem has failed, 


A blocking Windows Sockets 1.1 call is in progress, 
or the service provider is still processing a callback 
function. 


Not enough free memory available to complete the 
Operation. | | 

One or more of the values in the /ohEvents array is 
not a valid event object handle. 

The cEvents parameter does not contain a valid 
handle count. 


The WSAWaitForMultipleEvents function returns when any one or all of the specified 
objects are in the signaled state, or when the time-out interval elapses. This function is 
also used to perform an alertable wait by setting the parameter fAltertable to be TRUE. 
This enables the function to return when the system queues an I/O completion routine to 


be executed by the calling thread. 


When fWaitAll is TRUE, the function’s wait condition is satisfied only when the state of all 
objects is signaled at the same time. The function does not modify the state of the — 
specified objects until all objects are simultaneously signaled. 


Applications that simply need to enter an alertable wait state without waiting for any 
event objects to be signaled should use the Win32 SleepEx function. — 
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Version: Requires Windows Sockets 2.0. _ 
Header: Declared in Winsock2.h. 
Library: Use Ws2_32.lib. 


Windows Sockets Programming Considerations Overview, Microsoft Windows-Specific 
Extension Functions, WSACloseEvent, WSACreateEvent 
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CHAPTER 9Q 


Winsock 2 Structures and 
Enumerations 


Windows Sockets Structures in the API 


This chapter lists the structures used with Windows Sockets 2. 


AFPROTOCOLS 


The Windows Sockets AFPROTOCOLS structure supplies a list of protocols to which 
application programmers can constrain queries. The AFPROTOCOLS structure is used 
for query purposes only. 


Members 
iAddressFamily 
Address family to which the query is to be constrained. 


iProtocol 
Protocol to which the query is to be constrained. 


Remarks 


The members of the AFPROTOCOLS structure are a functional pair, and only have 
meaning when used together, as protocol values have meaning only within the context 
of an address family. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. — 


WSAQuerySet, WSALookupServiceBegin, NSPLookupServiceBegin 
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BLOB 


A Windows Sockets BLOB structure, derived from Binary Large Object, contains 
information about a block of data. | 


Members 


cbSize 
Size of the block of data pointed to by pBlobData, in bytes. 


pBlobData 
Pointer to a block of data. 


Remarks 


The structure name BLOB comes from the acronym BLOB, which stands for Binary 
Large Object. 


This structure does not describe the nature of the data pointed to by pBlobData. 


Note Windows Sockets defines a similar BLOB structure in Wtypes.h. Using both 
header files in the same source code file creates redefinition compile-time errors. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Wtypes.h. 


SERVICE_INFO 


SADDR_INFO 


The Windows Sockets CSADDR_INFO structure contains Windows Sockets address 
information for a network service or name space provider. The GetAddressByName 
function obtains Windows Sockets address information using CSADDR_INFO 
structures. 


es 
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Members 


LocalAddr 


Specifies a Windows Sockets local address. | 
In a client application, pass this address to the bind function to obtain access to a 


network service. 


In a network service, pass this address to the bind function so that the service is 
bound to the appropriate local address. 


RemoteAddr 


Specifies a Windows Sockets remote address. There are several uses for this remote 


address: 


e You can use this remote address to connect to the service through the connect 
function. This is useful if an application performs send/receive operations that 
involve connection-oriented protocols. 


e You can use this remote address with the sendto function when you are 
communicating over a connectionless (datagram) protocol. If you are using a 
connectionless protocol, such as UDP, sendto is typically the way you pass data to 


the remote system. 


iSocketType 


Specifies the type of the Windows socket. The following socket types are defined in 


Winsock.h. 
Value 


SOCK_STREAM 


SOCK_DGRAM 


SOCK_RDM 


SOCK_SEQPACKET 


iProtocol 


Socket type 


Stream. This is a protocol that sends data as a stream of 
bytes, with no message boundaries. | 


Datagram. This is a connectionless protocol. There is no 
virtual circuit setup. There are typically no reliability 
guarantees. Services use recvfrom to obtain datagrams. 
The listen and accept functions do not work with 
datagrams. 


Reliably-Delivered Message. This is a ptetocdl that 
preserves message boundaries in data. 


Sequenced packet stream. This is a protocol that | is 


essentially the same as SOCK_RDM. 


Specifies a value to pass as the protocol parameter to the socket function to Open a 


socket for this service. 
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Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Nspapi.h. 


bind, connect, GetAddressByName, recv, send, sendto 


fd_set 


The Windows Sockets fd_set structure is used by various Windows Sockets functions 
and service providers, such as the select function, to place sockets into a “set” for 
various purposes, such as testing a given socket for readability using the readfds 


parameter of the select function. 


Members 


fd_count 
Number of sockets in the set. 


fd_array 
Array of sockets that are in the set. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


select, WSAAsyncSelect, WSAEventSelect 


FLOWSPEC 


The FLOWSPEC structure is defined in the Quality of Service (QOS) section of the SDK. 
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hostent 


The Windows Sockets hostent structure is used by functions to store information about 
a given host, such as host name, IP address, and so forth. An application should never 
attempt to modify this structure or to free any of its components. Furthermore, only one 
copy of the hostent structure is allocated per thread, and an application should therefore 
copy any information that it needs before issuing any other Windows Sockets API calls. 


h_name 
Official name of the host (PC).If using the DNS or similar resolution system, it is the 
Fully Qualified Domain Name (FQDN) that caused the server to return a reply. If using 
a local hosts file, it is the first entry after the IP address. 


h_aliases 
Null-terminated array of alternate names. 


h_addrtype 
Type of address being returned. 
h_length 
Length of each address, in bytes. 
h_addr_list 
Null-terminated list of addresses for the host. Addresses are returned in network byte 


order. The macro h_addr is defined to be h_addr_list[0] for compatibility with older 
software. . 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


gethostbyaddr 


in_addr 


The Windows Sockets in_addr structure represents a host by its Internet address. 
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Members 
S_un_b | 
Address of the host formatted as four u_chars. 


S un w 
Address of the host formatted as two u_ shorts. 


S_addr 
Address of the host formatted as a u_long. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


per pers ees Sian Se sess eee 


inet_addr, inet_ntoa, SOCKADDR 


linger 


The Windows Sockets linger structure maintains information about a specific socket that 
specifies how that socket should behave when data is queued to be sent and the 
closesocket function is called on the socket. 


Members 


|_onoff | - meee 
Specifies whether a socket should remain open for a specified amount of time after a 
closesocket function call to enable queued data to be sent. 


I_linger 
Enabling SO_LINGER also disables SO_DONTLINGER,, and vice versa. Note that if — 
SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no time- 


out value is specified. In this case, the time-out used is implementation dependent. 
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lf a previous time-out has been established for a socket (by enabling SO_LINGER), 
this time-out value should be reinstated by the service provider. 


Remarks 

To enable SO_LINGER, the application should set tI _onoff to a nonzero value, set 
|_linger to zero or the desired time-out (in seconds), and call the setsockopt function. 
To specify SO_DONTLINGER (that is, disable SO_LINGER) |_onoff should be set to 
zero and setsockopt should be called. Note that enabling SO_LINGER with a nonzero 
time-out on a nonblocking socket is not recommended. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


setsockopt, getsockopt, closesocket 


NS SERVICE_INFO 


The Windows Sockets NS_ SERVICE_ INFO structure contains information about a 
network service or a network service type in the context of a specified name space, ora 
_ set of default name spaces. 


Members 


dwNameSpace 
Specifies the name space or a set of default name spaces to whieh this service 


information applies. | 
Use one of the following constant values to specify a name space. 


Value Name space 
NS_ DEFAULT A set of default name spaces. The set of default name spaces 


typically includes all the name spaces installed on the system. 
te System administrators, however, can exclude paliguat name 
| _ spaces from the set. : 
NS_DNS =——~——___ The Domain Name gee, used in the Internet to resolve the 
| | name of the host. . | 
(continued) 
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Value Name space 

NS_MS The Microsoft name space. 

NS_NDS The NetWare 4 provider. 

NS_NETBT The NetBIOS over TCP/IP layer. The operating system 
registers their computer names with NetBIOS. This name 
space is used to convert a computer name to an IP address 
that uses this registration. 

NS_NIS 

NS_SAP The NetWare Service Advertising Protocol. This can access 
the Netware bindery, if appropriate. NS_SAP is a dynamic 
name space that enables the registration of services. 

NS_STDA | 


Lookup value in the <systemroot>\system32\drivers\etc\ 
posts file. 
Local TCP/IP name resolution mechanisms, including 


comparisons against the local host name and lookup value in 
the cache of host to IP address mappings. 


NS_TCPIP_HOSTS 


NS_TCPIP_LOCAL 


NS_WINS 


The Windows Internet Name System (WINS) name space. 
NS_X500 The X.500 directory service name space. 
Servicelnfo 


A SERVICE_INFO structure that contains information about a network service or 
network service type. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Nspapi.h. 
Unicode: Declared as Unicode and ANSI structures. 


PROTOCOL_INFO 


The Windows Sockets PROTOCOL. INFO structure contains information about a 
protocol. | 
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Members 


dwServiceFlags 
A set of bit flags that specifies the services ee by the protocol. One or more of 
the following bit flags may be set. 


Value Meaning 


XP_CONNECTIONLESS If this flag is set, the protocol provides 
| connectionless (datagram) service. If this flag is 
clear, the protocol provides connection-oriented 
data transfer. 


XP_GUARANTEED_DELIVERY __ If this flag is set, the protocol guarantees that all 
data sent will reach the intended destination. If 
this flag is clear, there is no such guarantee. 


XP_GUARANTEED_ORDER If this flag is set, the protocol guarantees that 
| data will arrive in the order in which it was sent. 
Note that this characteristic does not guarantee 
delivery of the data, only its order. If this flag is 
clear, the order of data sent is not guaranteed. 


XP_MESSAGE_ORIENTED If this flag is set, the protocol is message- 
oriented. A message-oriented protocol honors 
message boundaries. If this flag is clear, the 
protocol is stream oriented, and the concept of 
message boundaries is irrelevant. 


XP_PSEUDO_STREAM If this flag is set, the protocol is a message- 
| oriented protocol that ignores message 
boundaries for all receive operations. 


This optional capability is useful when you do not 
want the protocol to frame messages. An 
application that requires stream-oriented 
characteristics can open a socket with type 
SOCK_STREAM for transport protocols that 

- support this functionality, regardless of the value 
of iSocketType. 


(continued) — 
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(continued) 
Value 
XP_GRACEFUL_CLOSE 


XP_EXPEDITED_DATA 
XP_CONNECT_DATA 
XP_DISCONNECT_DATA 
XP_SUPPORTS_BROADCAST 
XP_SUPPORTS_MULTICAST 


XP_BANDWIDTH_ALLOCATION 
XP_FRAGMENTATION 


XP_ENCRYPTS 


iAddressFamily 


Meaning 


If this flag is set, the protocol supports two-phase 
close operations, also known as graceful close 
operations. If this flag is clear, the protocol 
supports only abortive close operations. 


If this flag is set, the protocol supports expedited 
data, also known as urgent data. 


If this flag is set, the protocol supports 
connect data. 


If this flag is set, the protocol supports 
disconnect data. 


If this flag is set, the protocol supports a 
broadcast mechanism. 


If this flag is set, the protocol supports a 
multicast mechanism. 


If this flag is set, the protocol supports a 
mechanism for allocating a guaranteed 
bandwidth to an application. 

If this flag is set, the protocol supports message 
fragmentation; physical network MTU is hidden 
from applications. 

If this flag is set, the protocol supports data 
encryption. 


Value to pass as the af parameter when the socket function is called to open a socket 
for the protocol. This address family value uniquely defines the structure of protocol 
addresses, also known as sockaddr structures, used by the protocol. 


iMaxSockAddr 


Maximum length of a socket address supported by the protocol. 


iMinSockAddr 


Minimum length of a socket address supported by the protocol. 


iSocketType 


Value to pass as the type parameter when the socket function is called to open a 


socket for the protocol. 


Note that if XP_PSEUDO_STREAM is set in dwServiceFlags, the application can 
specify SOCK_STREAM as the type parameter to socket, regardless of the value of 


_ iSocketType. 
iProtocol 


Value to pass as the protoco/ parameter when the socket function is called to open a 


socket for the protocol. 
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dwMessageSize 
Maximum message size supported by the protocol. This is the maximum size of a 
message that can be sent from or received by the host. For protocols that do not 
support message framing, the actual maximum size of a message that can be sent to 
a given address may be less than this value. 


The following special message size values are defined. 


Value Meaning 

0 The protocol is stream-oriented; the concept of message size is 
not relevant. 

OxFFFFFFFF The protocol is message-oriented, but there is no maximum 


message size. 


IpProtocol — | | : 
Points to a zero-terminated string that supplies a name for the protocol; for. 
example, “SPX2.” 


Version: Requires Windows Sockets 1.1 or later. 
Header: Declared in Nspapi.h. 
Unicode: Declared as Unicode and ANSI structures. 


EnumProtocols, socket 


protoent 


The Windows Sockets protent structure contains the name and protocol numbers that 
correspond to a given protocol name. Applications must never attempt to modify this 
structure or to free any of its components. Furthermore, only one copy of this structure is 
allocated per thread, and therefore, the application should copy any information it needs 
before issuing any other Windows Sockets function calls. | 


Members 
p_name 
Official name of the protocol. 
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inated array of alternate names 


term 


Null- 


p_aliases 
p_proto 


Protocol number, in host byte order. 
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SERVICE_ADDRESS 


The Windows Sockets SERVICE_ADDRESS structure contains address information for 
a service. The structure can accomodate many types of Interprocess Communications 
(IPC) mechanisms and their address forms, including Remote Procedure Calls (RPC), 
named pipes, and sockets. | 


Members 

dwAddressType | | 
Address family to which the socket address pointed to by IpAddress belongs. 

dwAddressFlags | | | 
Set of bit flags that specify properties of the address. The following bit flags are 
defined. 
Value Meaning 
SERVICE_ADDRESS__If this bit flag is set, the service supports connection- 
FLAG_RPC_CN oriented RPC over this transport protocol. 
SERVICE_ADDRESS__ If this bit flag is set, the service supports datagram- 
FLAG_RPC_DG oriented RPC over this transport protocol. 
SERVICE_ADDRESS____ If this bit flag is set, the service supports NetBIOS RPC 
FLAG_RPC_NB over this transport protocol. 

dwAddressLength | 
Size, in bytes, of the address. 

dwPrincipalLength | 
Reserved for future use. Must be zero. _ : 

IpAddress _ | | 7 
Pointer to a socket address of the appropriate type. 

IpPrincipal 


Reserved for future use. It must be null. 
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aS 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Nspapi.h. 


SERVICE_ADDRESSES, SERVICE_INFO 


SERVICE ADDRESSES 


The Windows Sockets SERVICE_ADDRESSES structure contains an array of 
SERVICE_ADDRESS data structures. 


Members 


-~ dwAddressCount 
pecifies the number of SERVICE_ADDRESS structures in the Addresses array 


Addresses | 
An array of SERVICE_ADDRESS data structures. Each SERVICE_ADDRESS 
structure contains information about a network service address. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Nspapi.h. 


SERVICE_ADDRESS, SERVICE_INFO | | 7 


SERVICE_INFO 


The Windows Sockets SERVICE_IN O structure contains information about a network 
service or a network service type. 
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Members 


IpServiceType 
Pointer to a GUID that is the type of the network service. 


IpServiceName 
Pointer to a zero-terminated string that is the name of the network service. 


If you are calling the SetService function with the dwNameSpace parameter set to 
NS_DEFAULT, the network service name must be a common name. A common 
name is what the network service is commonly known as. An example of a common 
name for a network service is “My SQL Server’. 


If you are calling the SetService function with the dwNameSpace parameter set to a 
specific service name, the network service name can be a common name or a 
distinguished name. A distinguished name distinguishes the service to a unique 
location with a directory service. An example of a distinguished name for a network 
service is “MS\\SYS\\NT\\DEV\\My SQL Server’. 


IpComment 
Pointer to a zero-terminated string that is a comment or description for the network 
service. For example, “Used for development upgrades.” 

IpLocale 
Pointer to a zero-terminated string that contains locale information. 

dwDisplayHint 
Specifies a hint as to how to display the network service in a oMiele browsing user 
interface. This can be one of the following values. 


Value as | Meaning 3 
RESOURCEDISPLAYTYPE_ Displays the network service as a domain. 
| ~DOMAIN : ie: | 


RESOURCEDISPLAYTYPE_ Displays the network service as a ille: 
FILE | ae 


RESOURCEDISPLAYTYPE_ The method used to display the alg does not 
GENERIC matter. 


RESOURCEDISPLAYTYPE_ | Displays the network service asa group. 
GROUP | 


(continued) 
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(continued) 
Value Meaning 


RESOURCEDISPLAYTYPE_ ___ Displays the network service as a server. 
SERVER | 


RESOURCEDISPLAYTYPE_ ___ Displays the network service as a sharepoint. 
SHARE | | 


RESOURCEDISPLAYTYPE_ ___ Displays the network service as a tree. 
TREE 


dwVersion 
Version information for the network service. The high word of this value specifies a 
major version number. The low word of this value specifies a minor version number. 


dwTime 
Reserved for future use. Must be set to zero. 


IpMachineName 
Pointer to a zero-terminated string that is the name of the computer on which the 
network service is running. 


lpServiceAddress 
Pointer to a SERVICE_ADDRESSES structure that contains an array of 
SERVICE_ADDRESS structures. Each SERVICE_ADDRESS structure contains 
information about a network service address. 


A network service can call the getsockname function to determine the local address 
of the system. 


ServiceSpecificinfo 
A BLOB structure that specifies service-defined information. 


Note In general, the data pointed to by the BLOB structure’s pBlobData member 
must not contain any pointers. That is because only the network service knows the 
format of the data; copying the data without such knowledge would lead to pointer 
invalidation. If the data pointed to by pBlobData contains variable-sized elements, 
offsets from pBlobData can be used to indicate the location of those elements. There 
is one exception to this general rule: when pBlobData points to a 
SERVICE_TYPE_INFO_ABS structure. This is possible because both the 
SERVICE_TYPE_INFO_ABS structure, and any SERVICE_TYPE_VALUE_ABS 
structures it contains are predefined, and thus their formats are known to the 
operating system. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Nspapi.h. 


~ Unicode: Declared as Unicode and ANSI structures. 


Chapter 9 Winsock 2 Structures and Enumerations 393 


BLOB, GetService, NS_SERVICE_INFO, SetService, SERVICE_ADDRESS, 
SERVICE ADDRESSES, SERVICE TYPE INFO ABS. 
SERVICE TYPE VALUE ABS 


SERVICE_TYPE_INFO_ABS 


The Windows Sockets SERVICE_TYPE_INFO_ABS structure contains information 
about a network service type. You use a SERVICE_TYPE_INFO_ABS structure to adda 
network service type to a name space. 


Members 


IpTypeName 
Pointer to a zero- -terminated string that is the name of the network service type. This 
name is the same in all name spaces, and is used by the monly pen y hae and © 
-GetNameByType functions. 


dwValueCount | 
Number of SERVICE_TYPE_VALUE_ABS structures in the Values member array 
that follows dwValueCount. 


Values[1] 
Array of SERVICE_TYPE_VALUE_ABS structures. 


Each of these structures contains information about a service type value that the 
operating system or network service may need when an instance of this network 
service type is registered with a name space. 


The information in these structures may be specific to a name-space. For example, if 
a network service uses the SAP name space, but does not have a GUID that contains 
the SAP identifier (SAPID), it defines the SAPID in a SERVICE_TYPE_VALUE_ABS 
structure. | | 


Remarks 

When you use the SetService function to add a network service type to a name space, 
the SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificinfo BLOB 
member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member 
generally should not contain pointers, an exception is made in the case of the 
SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures. 
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Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Nspapi.h. 


Unicode: Declared as Unicode and ANSI structures. 


SetService, SERVICE_INFO, SERVICE _TYPE_VALUE_ABS 


SERVICE_TYPE_VALUE_ABS 


The Windows Sockets SERVICE_TYPE_VALUE_ABS structure contains information 
about a network-service type value. This information may be specific to a name space. 


Members 


dwNameSpace 


Specifies the name space, or a set of default name spaces, for which the network 
service type value is intended. Name-space providers will look only at values intended 
for their name space. 


Use one of the following constants to specify a name space. 
Value Name space 


NS_DEFAULT A set of default name spaces. The function queries each name 
space within this set. The set of default name spaces typically 
includes all the name spaces installed on the system. System 
administrators, however, can exclude particular name spaces 
from the set. NS_DEFAULLT is the value that most applications 
should use for dwNameSpace. 


NS_DNS The Domain Name System used in the Internet for host name 
resolution. 


Value 


NS_NETBT 


NS_SAP 


NS_TCPIP_HOSTS 


NS_TCPIP_LOCAL 


dwValueType 


Type of the value data. 


Value 


REG_BINARY 
REG _DWORD 
REG_MULTI_SZ 


REG_SZ 


, dwValueSize 
Size of the value data. 


Chapter 9 Winsock 2 Structures and Enumerations 395 


Name space 


The NetBIOS over TCP/IP layer. All 

Windows NT/Windows 2000 systems register their computer 
names with NetBIOS. This name space is used to convert a 
computer name to an IP address that uses this registration. 
Note that NS_NETBT may access a WINS server to perform 
the resolution. 

The Netware Service Advertising Protocol. This may access 
the Netware bindery if appropriate. NS_SAP is a dynamic 
name space that allows registration of services. 

Lookup value in the <systemroot>\system32\drivers\etc\ 
hosts file. 

Local TCP/IP name resolution mechanisms, including 
comparisons against the local host name and looks up host 
names and IP addresses in cache of host to IP address 
mappings. 


Specify one of the following types. 
Meaning 


Binary data in any form. 
A 32-bit number. 


An array of nul terminaiee strings, terminated by two null 
characters. 


A null-terminated string. 


in bytes. In the case of REG_SZ and REG_MULTI_SZ string 


data, the terminating characters are counted as part of the size. 


IpValueName 


Pointer to a zero-terminated string that is the name of the value. This name is specific 


to a name space. 


Several commonly used value name strings are pecorataa with defined constants. 
_ These name strings include the following. 3 


| Constant | Name string | 
_SERVICE_TYPE_VALUE_SAPID “Sapld” 
_ SERVICE_TYPE_VALUE_CONN “ConnectionOriented” 


- SERVICE_TYPE_VALUE_TCPPORT  “TcpPort” 
-SERVICE_TYPE_VALUE_UDPPORT  “UdpPort” 


[pValue 


Pointer to the value data. 
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Remarks 


When you use the SetService function to add a network service type to a name space, 
a SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificInfo BLOB 
member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member 
generally should not contain pointers, an exception is made in the case of the 
SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures. 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 


Header: Declared in Nspapi.h. 
Unicode: Declared as Unicode and ANSI structures. 


SetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS 


sockaddr 


The Windows Sockets sockaddr structure varies depending on the protocol selected. 
Except for the sa_family parameter, sockaddr contents are expressed in network byte 


order. 


In Windows Sockets 2, the name parameter is not strictly interpreted as a pointer to a 
sockaddr structure. It is presented in this manner for Windows Sockets compatibility. 
The actual structure is interpreted differently in the context of different address families. 
The only requirements are that the first u_short is the address family and the total size 


of the memory buffer in bytes is namelen. 
The structure below is used with TCP/IP. Other protocols use similar structures. 


ersion: Requires Windows Sockets 2.0. 
eader: Declared in Winsock2.h. 
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SOCKADDR_IRDA 


The Windows Sockets SOCKADDR_IRDA structure is used in conjunction with IrDA 
socket operations, defined by address family AF_IRDA. 


Members 


irdaAddressFamily 
Address family. This member is always AF_IRDA. 


irdaDevicelD | | 
Device identifier (ID) of the IrDA device to which the client wants to issue the connect 


function call. Ignored by server applications. 


irdaServiceName 
Well-known service name associated with a server application. Specified by servers 


during their bind function call. 


Remarks 


Client applications make use of each field in the SOCKADDR_IRDA structure. The 
irdaDevicelD member is obtained by a previous discovery operation performed by 
making a setsockopt(IRLMP_ENUMDEVICES) function call. For more information on 
performing a discovery operation, see the Notes for IrDA Sockets section in the Remarks 


section of setsockopt. 


The irdaServiceName member is filled with the well-known value that the server 
application specified in its bind function call. 


See 


SoBe 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Af_irda.h. 


getsockopt, setsockopt, bind, connect 


SOCKET ADDRESS 


The SOCKET_ADDRESS structure stores protocol-specific address information. 
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Members 


IpSockaddr 
Pointer to a socket address 


iSockaddrLength _—_ ; | 
Length of the socket address, in bytes. _ | 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


WSAloctil, Ploctl 


timeval 


The Windows Sockets timeval structure is used to specify time values. It is associated 
with the BSD file Time.h. 


lembers 


tv_sec 
Time value, in seconds. 


tv_usec 
Time value, in microseconds. 


Version: Requires Windows Sockets 20. 
Header: Declared in Winsock2.h. | - | 


linger, select 
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TRANSMIT_FILE_BUFFERS 


The Windows Sockets TRANSMIT_FILE_BUFFERS structure specifies data to be 
transmitted before and after file data during a TransmitFile function file transfer 


operation. 


Members 


Head 
Pointer to a buffer that contains data to be transmitted before the file data is 


transmitted. 


HeadLength | 
Number of bytes in the buffer pointed to by Head that are to be transmitted. 


Tail | | 
Pointer to a buffer that contains data to be transmitted after the file data is transmitted. 
—-- TailLength 
~ Number of bytes of data in the buffer pointed to by the Tail member that are to be 
transmitted. | 


Version: Requires Windows Sockets 1.1 or later. Not supported on Windows 95. 
Header: Declared in Winsock.h. | | 


TransmitFile 


-WSABUF — 


The Windows Sockets WSABUF structure enables the creation or manipulation ofa 
data buffer. a | a oo oe ee | 
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Members 
len 


Length of the buffer. 


buf 


Pointer to the buffer. 


Version: Requires Windows Sockets 2.0. 


insock2.h. 


W 


in 


- Declared | 


Header 


WSADATA 


The members of the Windows Sockets WSADATA structure are 


. 


SS 


Boe 


Members 


wVers 


ion 


Version of the Windows Sockets specification that the Ws2_32.dll expects the caller 


to use. 
wHighVersion 


Highest version of the Windows Sockets specification that this .dll can support (also 


encoded as above). Normally th 


szDescription 


fon. 


the same as wVers 


is Is 


f the 


in length) can 
the most likely use 


that an application can put this to is to display it (possibly truncated) in a status 


message. 
szSystemStatus 


tion o 


Ip 


descr 


lesa 


.dil copi 


_32 


into which the Ws2 
The text (up to 256 characters 


lementat 
contain any characters except control and formatting characters 


ing | 


Null-terminated ASCII str 


Windows Sockets 


ion 


imp 


to which the WSs2 
configuration information. The Ws2_32.dll should use this parameter only if the 


levant status or 


les re 


32.dll cop 


ing in 


Null-terminated ASCII str 


it should not be considered as 


information might be useful to the user or support staff 
an extension of the szDescription parameter. 
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iMaxSockets 
Retained for backward compatibility, but should be ignored for Windows Sockets 


version 2 and later, as no single value can be appropriate for all underlying service 
providers. 

iMaxUdpDg 
Ignored for Windows Sockets version 2 and onward. iMaxUdpDg is retained for 
compatibility with Windows Sockets specification 1.1, but should not be used when 
developing new applications. For the actual maximum message size specific to a 
particular Windows Sockets service provider and socket type, applications should use 
getsockopt to retrieve the value of option SO_MAX_MSG_SIZE after a socket has 
been created. 


IpVendorinfo 
Ignored for Windows Sockets version 2 and onward. It is retained for compatibility 


with Windows Sockets specification 1.1. Applications needing to access vendor- 
specific configuration information should use getsockopt to retrieve the value of 
option PVD_CONFIG. The definition of this value (if utilized) is beyond the scope of 
this specification. | | 


Note An application should ignore the iMaxsockets, iMaxUdpDg, and IpVendorinfo 
members in WSAData if the value in wVersion after a successful call to WSAStartup is 
at least 2. This is because the architecture of Windows Sockets has been changed in 
version 2 to support multiple providers, and WSAData no longer applies to a single 
vendor's stack. Two new socket options are introduced to supply provider-specific 
information: SO_MAX_MSG_SIZE (replaces the iMaxUdpDg element) and 
PVD_CONFIG allows any other provider-specific configuration to occur). 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


WSANAMESPACE_INFO 


The Windows Sockets WSANAMESPACE_INFO structure contains all registration 
information for a name space provider. : 
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Members 
NSProviderld 
Unique identifier for this name-space provider. 


_dwNameSpace 
Name space supported by this implementation of the provider. 


fActive 
If TRUE, indicates that this provider is active. If FALSE, the provider is inactive and is 
not accessible for queries, even if the query specifically references this provider. 


dwVersion 
Name space—version identifier. 


Ipszidentifier 
Display string for the provider. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Unicode: Declared as Unicode and ANSI structures. 


WSANETWORKEVENTS 


The Windows Sockets WSANETWORKEVENTS structure is used to store a socket’s 
internal information about network events. 


Members 


INetworkEvents 
Indicates which of the FD_XXX network events have occurred. 


iErrorCodes 
An array that contains any associated error codes, with an array index that 
corresponds to the position of event bits in INetworkEvents. The identifiers 
FD_READ_BIT, FD_WRITE_BIT and other can be used to index the iErrorCodes 


array. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. - 
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WSAEnumNetworkE vents, WSAEventSelect 


WSAOVERLAPPED 


The Windows Sockets WSAOVERLAPPED structure provides a communication medium 
between the initiation of an overlapped I/O operation and its subsequent completion. The 
WSAOVERLAPPED structure is designed to be compatible with the Win32 
OVERLAPPED structure: 


Members 


Internal 
Reserved for internal use. The Internal member is used internally by the entity that 
implements overlapped I/O. For service providers that create sockets as installable 
file system (IFS) handles, this parameter is used by the underlying operating system. 
Other service providers (non-IFS providers) are free to use this parameter as 
necessary. | 


InternalHigh 
Reserved. Used internally by the entity that implements overlapped I/O. For service 
_ providers that create sockets as IFS handles, this parameter is used by the underlying 
operating system. NonlFS providers are free to use this parameter as necessary. 


Offset 
Reserved for use by service providers. 


OffsetHigh 
Reserved for use by service providers. 


hEvent 
If an overlapped I/O operation is issued without an I/O completion routine 
(jpoCompletionRoutine is null), then this parameter should either contain a valid handle 
to a WSAEVENT object or be null. If />CompletionRoutine is non-null then 
applications are free to use this parameter as necessary. | 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. me a 
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WSASend, WSARecv, WSAGetOverlappedResult 


WSAPROTOCOL_INFO 


The Windows Sockets WSAPROTOCOL_INFO structure is used to store or retrieve 


complete information for a given protocol. 


oo 


iceFlags1 
Bitmask describing the services provided by the protocol. The following values are 


dwServ 


ble 
XP1_CONNECTIONLESS 


possi 


. If not set, the protocol supports 


Provides connectionless (datagram) service 
connection-oriented data transfer. 
XP1_GUARANTEED_DELIVERY 


Guarantees that all data sent will reach the intended destination. 
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XP1_GUARANTEED_ORDER 
Guarantees that data only arrives in the order in which it was sent and that it is not 
duplicated. This characteristic does not necessarily mean that the data is always 
delivered, but that any data that is delivered is delivered in the order in which it was 
sent. 

XP1_MESSAGE _ORIENTED 
Honors message boundaries—as opposed to a stream- oriented protocol where 
there is no concept of message boundaries. 

XP1_PSEUDO_STREAM 
A message-oriented protocol, but message boundaries are ignored for all receipts. 
This is convenient when an application does not desire message framing to be 
done by the protocol. 

XP1_GRACEFUL_CLOSE 
Supports two-phase (graceful) close. If not set, only abortive closes are performed. 

XP1_EXPEDITED_DATA 
Supports expedited (urgent) data. 

XP1_CONNECT_DATA 
Supports connect data. 

XP1_DISCONNECT_DATA 
Supports disconnect data. 

XP1_INTERRUPT 
Bit is reserved. 

XP1_SUPPORT_BROADCAST 
Supports a broadcast mechanism. 

XP1_SUPPORT_MULTIPOINT 
Supports a multipoint or multicast mechanism. Control and data plane attributes 
are indicated below. 

XP1_MULTIPOINT_CONTROL_PLANE 
Indicates whether the control plane is rooted (value = 1) or nonrooted (value = 0). 

XP1_MULTIPOINT_DATA_PLANE 

| Indicates whether the data plane is rooted (value = 1) or nonrooted (value = 0). 

- XP1_QOS_SUPPORTED 

| Supports quality of service requests. 

XP1 _UNI _SEND 
Protocol is unidirectional in the send direction. 

XP1_UNI_RECV 
Protocol is unidirectional in the recv direction. 

XP1 _IFS_ HANDLES 
Socket descriptors returned by the provider are epecting system Installable File 
System (IFS) handles. | 
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XP1 _PARTIAL_ MESSAGE 7 
~The MSG_PARTIAL flag is supported in WSASend and WSASendTo. 

Note that only one of XP1_UNI_SEND or XP1_UNI_RECV may be set. If a protocol 

can be unidirectional in either direction, two WSAPROTOCOL_INFOW structures 

should be used. When neither bit is set, the protocol is considered to be bidirectional. 
dwServiceFlags2 

Reserved for additional protocol-attribute definitions. 
dwServiceFlags3 

Reserved for additional protocol-attribute definitions. 

dwServiceFlags4 
Reserved for additional protocol-attribute definitions. 

dwProviderFlags 
Provides information about how this protocol is represented in the protocol catalog. 
The following flag values are possible: 

PFL_MULTIPLE_PROTO_ENTRIES 
Indicates that this is one of two or more entries for a single protocol (from a given 
provider) which is capable of implementing multiple behaviors. An example of this 
is SPX which, on the receiving side, can behave either as a message-oriented or a 
stream-oriented protocol. | 
PFL_RECOMMENDED_PROTO_ENTRY 
Indicates that this is the recommended or most frequently used entry for a protocol 
that is capable of implementing multiple behaviors. 
PFL_HIDDEN 
Set by a provider to indicate to the Ws2_32.dll that this 5 rotocsl should not be 
returned in the result buffer generated by WSAEnumProtocols. Obviously, a 
Windows Sockets 2 application should never see an entry with this bit set. 
PFL_MATCHES_PROTOCOL_ZERO 
Indicates that a value of zero in the protocol pale of socket or WSASocket 
matches this protocol entry. 

Providerld | 7 | | 
Globally unique identifier assigned to the provider by the service provider vendor. This 
value is useful for instances where more than one service provider is able to | 
implement a particular protocol. An application may use the dwProviderld value to 
distinguish between providers that might otherwise be eee lees 

dwCatalogEntryld 


Unique identifier aerigned by the WS2_ 32. DLL for each WSAPROTOCOL. INFOW 
structure. 
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WSAPROTOCOLCHAIN ProtocolChain; 


If the length of the chain is 0, this WSAPROTOCOL_INFOW entry represents a 
layered protocol which has Windows Sockets 2 SPI as both its top and bottom 
edges. If the length of the chain equals 1, this entry represents a base protocol 
whose Catalog Entry identifier is in the dwCatalogEntryld member of the 
WSAPROTOCOL_INFOW structure. If the length of the chain is larger than 1, this 
entry represents a protocol chain which consists of one or more layered protocols 
on top of a base protocol. The corresponding Catalog Entry identifiers are in the 
ProtocolChain.ChainEntries array starting with the layered protocol at the top (the 
zero element in the ProtocolChain.ChainEntries array) and ending with the base 
protocol. Refer to the Windows Sockets 2 Service Provider Interface specification 
for more information on protocol chains. 


iVersion 
Protocol version identifier. 


iAddressFamily 
Value to pass as the address family parameter to the socket/WSASocket function in 
order to open a socket for this protocol. This value also uniquely defines the structure 
of protocol addresses SOCKADDRs used by the protocol. 


iMaxSockAddr 
Maximum address length. 


iMinSockAddr 
Minimum address length. 


iSocketType 
Value to pass as the socket type parameter to the socket function in order to open a 
socket for this protocol. 


iProtocol | 
Value to pass as the protocol parameter to the socket function in order to opena 
socket for this protocol. 


iProtocolMaxOffset 

_ Maximum value that may be added to iProtocol when supplying a value for the 
protoco/ parameter to socket and WSASocket. Not all protocols allow a range of 
values. When this is the case iProtocolMaxOffset is zero. 

iNetworkByteOrder 
Currently these values are manifest constants (BIGENDIAN and LITTLEENDIAN) - that 
indicate either big-endian or little-endian with the values O and 1 feo: 

iSecurityScheme 
Indicates the type of security scheme employed (if any). A value of 
SECURITY _ PROTOCOL_NONE is used for F protocols that do not incorporate security 
provisions. 
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dwMessageSize 
Maximum message size supported by the protocol. This is the maximum size that can 
be sent from any of the host’s local interfaces. For protocols that do not support 
message framing, the actual maximum that can be sent to a given address may be 
less. There is no standard provision to determine the maximum inbound message 
size. The following special values are defined: 


0 
The protocol is stream-oriented and hence the concept of message size is not 
relevant. 

Ox1 


The maximum outbound (send) message size is dependent on the underlying 
network MTU (maximum sized transmission unit) and hence cannot be known until 
after a socket is bound. Applications should use getsockopt to retrieve the value 
of SO_MAX_MSG_SIZE after the socket has been bound to a local address. 


OxFFFFFFFF 
The protocol is message-oriented, but there is no maximum limit to the size of 
messages that may be transmitted. 


dwProviderReserved 
Reserved for use by service providers. 


szProtocol 


Array of characters that contains a human-readable name identifying the protocol, for 
example “SPX2”. The maximum number of characters allowed is 
WSAPROTOCOL_LEN, which is defined to be 255. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Unicode: Declared as Unicode and ANSI structures. 


WSAEnumProtocols, WSASend, WSASendTo, getsockopt, socket 


WSAPROTOCOLCHAIN 


The Windows Sockets WSAPROTOCOLCHAIN structure contains a counted list of 


Catalog Entry identifiers that comprise a protocol chain. This structure is defined as 
follows: | 
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Members 
ChainLen | 
Length of the chain. The following settings apply: 
Setting ChainLen to zero indicates a layered protocol 
Setting ChainLen to one indicates a base protocol 


Setting ChainLen to greater than one indicates a protocol chain. 


ChainEntries 
Array of protocol chain entries. 


Remarks 


If the length of the chain is larger than 1, this structure represents a protocol chain whic 
consists of one or more layered protocols on top of a base protocol. The corresponding 
Catalog Entry IDs are in the ProtocolChain.ChainEntries array starting with the layered 
protocol at the top (the zeroth element in the ProtocolChain.ChainEntries array) and 


ending with the base protocol. Refer to Windows Sockets 2 Service Provider Interface 
for more information on protocol chains. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 


es 


WSAEnumProtocols 


WSAQUERYSET > 


The Windows Sockets WSAQUERYSET structure provides relevant information about a 
given service, including service class ID, service name , applicable name-space identifier 


and protocol information, as well as a set of transport addresses at which the service 
listens. 


oa 


ne 
2 
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(continued) 


Members 


dwSize 
; Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism. 


dwOutputFlags 
Ignored for queries. 


IpszServiceInstanceName 
Optional) Referenced string contains service name. The semantics for using 
wildcards within the string are not defined, but can be supported by certain name 
space providers. 


IpServiceClassid 
Required) The GUID corresponding to the service class. 


IpVersion 
Optional) References desired version number and provides version comparison 
semantics (that is, version must match exactly, or version must be not less than the 
value supplied). 


lpszComment 
Ignored for queries. 


dwNameSpace 
Identifier of a single name space in which to constrain the search, or NS_ALL to 
include all name spaces. 


IpNSProviderld 
_ (Optional) References the GUID of a specific name-space provider, and limits the 
query to this provider only. 


IpszContext | 
(Optional) Specifies the starting point of the query in a hierarchical name space. 


dwNumberOfProtocols 
Size of the protocol constraint array, can be zero. 


lpafpProtocols oo oe 
(Optional) References an array of AFPROTOCOLS structure. Only services that 
utilize these protocols will be returned. | 


IpszQueryString | 
- (Optional) Some name spaces (such as Whois++) support enriched SQL-like queries 
that are contained in a simple text string. This parameter is used to specify that string. 
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dwNumberOfCsAddrs 
Ignored for queries. 


lpcsaBuffer 
Ignored for queries. 


IpBlob 
(Optional) This is a pointer to a provider-specific entity. 


Remarks 


In most instances, applications interested in only a particular transport protocol should 
constrain their query by address family and protocol rather than by name space. This 
would allow an application that needs to locate a TCP/IP service, for example, to have its 
query processed by all available name spaces such as the local hosts file, DNS, 

and NIS. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Winsock2.h. 
Unicode: Declared as Unicode and ANSI structures. 


-WSAQuerySet, WSASetService, WSALookupServiceBegin, 
WSALookupServiceNext _ | 


WSASERVICECLASSINFO > 


The Windows Sockets WSASERVICECLASSINFO structure contains information about 
a specified service class. For each service class in Windows Sockets 2, there is a single 
WSASERVICECLASSINFO structure. 


Members 


IpServiceClassld 
Unique Identifier (GUID) for the service class. 


IpszServiceClassName | | 
Well known associated with the service class. 
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dwCount 
Number of entries in IpClassinfos. 


IpClassinfos | 
Array of WSANSCLASSINFOW structures that contains information about the service 


class. 


Version: Requires Windows Sockets 2.0. 


Header: Declared in Winsock2.h. 
Unicode: Declared as Unicode and ANSI structures. 


NSPGetServiceClassIinfo, NSPLookupServiceBegin 


WSATHREADID 


The Windows Sockets WSATHREADID structure enables a provider to identify a thread 
on which asynchronous procedure calls (APCs) can be queued using the 


WPUQueueApc function. 


Members 
ThreadHandle | 
Handle to the thread ID. 


Reserved 
Reserved. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUQueueApc, WSPloctl, WSPSend, WSPRecv 
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Windows Sockets Enumeration in the API 


The following enumeration is used in Windows Sockets: 
e WSAECOMPARATOR 


The following enumeration is obsolete: 
e GUARANTEE 


GUARANTEE 


The Windows Sockets GUARANTEE enumeration is no longer used. For information 


regarding the Windows 2000 implementation of Quality of Service, and the associated 
API, refer to Chapters 13 through 17 later in this volume. 


WSAECOMPARATOR 


-The Windows Sockets WSAECOMPARATOR enumeration type is used for version 
comparison semantics in Windows Sockets 2. 


Enumerator Value Meaning 
. COMP_EQUAL _ Used for determining whether version values are equal. 
COMP_NOTLESS Used for determining whether a version value is no less 


than a specified value. 


WSALookupServiceBegin, WSAQuerySet, NSPLookupServiceBegin, 
NSPLookupServiceNext, WSASetService, NSPSetService 
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CHAPTER 10 


Winsock 2 SPI Overview 


Welcome to Windows Sockets 2 SPI 


This chapter describes the Windows Sockets 2 Service Provider Interface (SPI). It 
consists, primarily, of information from the Windows Sockets 2 SPI specification, but also 
includes additional information. The information in this document is not presented in | 
exactly the same way as specification. 


Using the SPI Document 


This document provides the online material needed to create Windows Sockets service 
or transport providers for Windows operating systems, using the Microsoft 
implementation of Windows Sockets 2. It is intended as a reference tool and outlines the 
functions of the Windows Sockets SPI. , 


You should be familiar with Win32 programming concepts and the Windows Sockets API 
to make the best use of this document. Thus, you may want to refer to other references _ 
that provide a more systematic guide to writing Windows Sockets applications. 


Note This documentation is intended for service provider developers, also known as | 
transports. If you are developing a Windows Sockets 2 application, see chapters 6 
through 9 in this volume. 


Overview of the Windows Sockets 2 SPI 


Windows Sockets 2 utilizes the sockets paradigm that was first popularized by Berkeley 
- Software Distribution (BSD) UNIX. It was later adapted for Microsoft Windows in the — 
Windows Sockets 1.1. 


One of the primary goals of Windows Sockets 2 has been to provide a protocol- 
independent interface fully capable of supporting the emerging networking Men es 
such as real-time multimedia communications. | 


Windows Sockets 2 is an interface, not a protocol. As an niétiace. it is used to discover 
and utilize the communications capabilities of any number of underlying transport 

protocols. Because it is not a protocol, it does not in any way affect the bits on the wire, 
and does not need to be utilized on both ends of acommunications link. =| 
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Windows Sockets programming previously centered around TCP/IP. Some of the 
programming practices that worked with TCP/IP do not work with every protocol. As a 
result, the Windows Sockets 2 API added new functions where necessary that, in turn, 
must be implemented in the underlying service provider. | 


Windows Sockets 2 has changed its architecture to provide easier access to multiple 
transport protocols. Following the Windows Open System Architecture (WOSA) model, 
Windows Sockets 2 now defines a standard SPI between the application programming 
interface (API), with its functions exported from Ws2_32.dll, and the protocol stacks. 
Consequently, Windows Sockets 2 support is not limited to TCP/IP protocol stacks as is 
the case for Windows Sockets 1.1. For more information, see Windows Sockets 2 


Architectural Overview. 


There are new challenges in developing Windows Sockets 2 applications. When sockets 
only supported TCP/IP, a developer could create an application that supported only two 
socket types: connectionless and connection-oriented. Connectionless protocols used 
SOCK_DGRAM sockets and connection-oriented protocols used SOCK_STREAM 


_ sockets. Now, these are just two of the many new socket types. Additionally, developers 


can no longer rely on socket type to describe all the essential attributes of a transport 
protocol. 


The service provider is created by implementing the functions defined in this document. | 
This is a new challenge differing significantly from Windows Sockets 1.1. 


Windows Sockets 2 SPI Features 
The new Windows Sockets 2 extends functionality in a number of areas. 


Features | Description 

Access to protocols other than Allows an application to use the familiar socket 

TCP/IP interface to achieve simultaneous access to a 
number of installed transport protocols. 

Overlapped I/O with Incorporates the overlapped paradigm for socket 


scatter/gather I/O and incorporates scatter/gather capabilities as 
7 | well, following the model established in Win32 
environments. 


Protocol-independent name Includes a standardized set of functions for 
resolution facilities: querying and working with the myriad of name 
| resolution domains that exist today (for example 
DNS, SAP, and X.500). | 


Protocol-independent multicast Windows Sockets 2 applications discover what type 

and multipoint: of multipoint or multicast capabilities a transport 

| | provides and use these facilities in a generic 
manner. 
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Features | | Description 


Quality of Service (QOS) Establishes conventions applications use to 
negotiate required service levels for parameters 
such as bandwidth and latency. Other QOS-related 
enhancements mechanisms for network-specific 
QOS extensions. QOS implementation in Windows 
is explained in detail in its own section under 
Networking Services in the Platform SDK. 


Other frequently requested Incorporates shared sockets and conditional 
extensions acceptance; exchange of user data at connection 
| setup/teardown time; and protocol-specific 
extension mechanisms. 


Microsoft Extensions and the Windows Sockets 2 SPI 


The Windows Sockets 2 specification defines an extension mechanism that exposes 
advanced transport functionality to application programs. See the SPI: Function 
Extension Mechanism in the SPI section. The following Microsoft-specific extensions that 
were added to Windows Sockets 1.1 are also available to Windows Sockets 2 
applications: 


e AcceptEx — 

e GetAcceptExSockaddrs 
e TransmitFile 

e WSARecvEx 


These functions are not exported from the Ws2 32. dil; they are exported from 
Mswsock. dil. 


An application written to use the Microsoft-specific extensions to Windows Sockets will 
not run see over a Windows Sockets service provider that does not support those 
extensions. | 


Socket Handles for the Windows Sockets 2 SPI 


A socket handle can optionally be a file handle In Windows Sockets 2. It is possible to 
use socket handles with ReadFile, WriteFile, ReadFileEx, WriteFileEx, 
DuplicateHandle, and other Win32 functions. Not all transport service providers will 
support this option. For an application to run over the widest possible number of service 
providers, it should not assume that socket handles are file handles. 


Windows Sockets 2 has expanded certain functions used for transferring data between 
sockets using handles. The functions offer advantages specific to sockets for transferring 
data and include WSARecv, WSASend, and WSADuplicateSocket. | 
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Windows Sockets 2 Architectural Overview 


This chapter provides an overview of the Windows Sockets 2 architecture. It describes 
and illustrates the relationships between applications, the Windows Sockets 2 DLL and 
Windows Sockets service providers. A high-level view of the division of responsibilities 
between the Windows Sockets 2 DLL and the Windows Sockets service providers is also 
provided. | 


Windows Sockets 2 as a WOSA Component 


The Windows Sockets 2 network transport and name resolution services are provided as 
a Windows Open Services Architecture (WOSA) component. They consist of both an 
application programming interface (API) used by applications and service provider 
interfaces (SPIs) implemented by service providers. This document defines the service 
provider interfaces for data transport and name resolution. While it is designed to be a 
stand-alone reference for the implementers of Windows Sockets 2 service providers, 
developers are strongly encouraged to obtain and become familiar with the Windows 
Sockets 2 Application Programming Interface as well. 


WOSA provides a common set of interfaces for connecting front-end applications with 
back-end services. The front-end application and back-end services need not speak 
each other’s language in order to communicate as long as they both know how to talk to 
their respective WOSA interfaces. As a result, WOSA allows application developers and 
vendors of back-end services to mix and match applications and services to build 
solutions that shield programmers and users from the underlying complexity of the 
system. WOSA defines an abstraction layer to heterogeneous computing resources 
through the WOSA set of APIs. Because this set of APIs is extensible, new services and 
their corresponding APIs can be added as needed. Applications written to the WOSA 
APIs have access not only to the various computing environments supported today, but 
also to all additional environments as they become available. Moreover, applications 
don’t have to be modified in any way to enjoy this support. 


Each service recognized by WOSA also has a set of interfaces that service-provider 
vendors use to take advantage of the seamless interoperability that WOSA provides. To 
provide transparent access for applications, each implementation of a particular WOSA 
service simply needs to support the functions defined by its service provider interface. 


Like most WOSA components, Windows Sockets 2 uses a Windows Dynamic-Link 
Library (DLL) that allows applications and service providers software components to be 
bound together at runtime. In this way, applications are able to connect to services 
dynamically. An application needs to know only the definition of the interface, not its 
implementation. 
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Windows Sockets 2 DLLs 


Windows Sockets network services follow the WOSA model, meaning that there exists a 
Windows Sockets Application Programming Interface (API), which is the application 
programmer's access to network services, Windows Sockets Service Provider Interfaces 
(SPls) which are implemented by transport service providers and name resolution 

service provider vendors, and Ws2_32.dll. The Windows Sockets 2 WOSA- “compliant 
architecture is illustrated | in Figure 10-1. 


Windows Windows 
Sockets 2 Sockets 2 
Application Application 
Wi in d OWS scanner 
Sockets 2 API 
i 
Transport Name Space 
Functions ; Functions 
WS2_32.DLL 


Windows Sockets 2 Windows Sockets 2 _ 
Transport SPI 7 nT Name Space SPI 


Transport | Transport Name Space Name Space 
Service _ Service Service _ Service 


Provider | Provider Provider Provider 


Figure 10-1: Winsock 2 WOSA-Compliant Architecture. 


The SPI is intended to be used within all 32-bit implementations and versions of 
_ Microsoft® Windows® including Windows® NT® and Windows® 95®. 


Function Interface Model 


Windows Sockets transport and name space service providers are DLLs witha single 
exported procedure entry point for the service provider initialization function 
~ WSPStartup or NSPStartup, respectively. All other service provider functions are made 
accessible to the Ws2_32.dll through the service provider’s dispatch table. Service 
provider DLL’s are loaded into memory by the Ws2_32.dll only when needse, be are 
unloaded when their services are no longer required. | 


The SPI also defines several circumstances in which a transport service provider calls 
up into the Ws2_32.dll (upcalls) to obtain DLL support services. The transport service 
provider DLL is given the Ws2_32.dll’s upeall ot table through the oar Oath 

| Ramet to WSPStartup. 
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Service providers should have their file extension changed from “DLL” to “.WSP” or 
“NSP”. This requirement is not strict. A service ployee will still operate with the — 
Ws2_32.dll with any file extension. 


Naming Conventions 
The Windows Sockets SPI uses the following function prefix naming convention. 


Prefix Meaning Description 

WSP Windows Sockets Service Transport service provider entry points 
Provider 

WPU | Windows Sockets Provider Ws2_32.dll entry points for service 
Upcall providers 

WSC Windows Sockets WS2_32.dll entry points for installation - 
Configuration applets 

NSP Name Space Provider Name space provider entry points 


As described above, these entry points are not exported (with the exception of 
WSPStartup and NSPStartup), but are accessed through an exchange of dispatch 
tables. 


Windows Sockets 2 Service Providers 


As shown in the figure, Windows Sockets 2 Architecture, there are two basic types of 
service providers: transport providers and name space providers. Examples of transport 
providers include protocol stacks such as TCP/IP or IPX/SPX, while an example of a 
name space provider would be an interface to the Internet's Domain Naming System 
(DNS). Separate sections of the service provider interface specification ss to each 
type of service provider. 


Transport and name space service providers must be registered with the Ws2_32.dil at 
the time they are installed. This registration need only be done once for each provider as 
the necessary information is retained in persistent storage. 


Transport Service Providers 


A given transport service provider supports one or more protocols. For example, a 
TCP/IP provider would supply (as a minimum) the TCP and UDP protocols, while an 
IPX/SPX provider might supply IPX, SPX, and SPX II. Each protocol supported by a 
particular provider is described by a WSAPROTOCOL_INFOW structure, and the total 
set of such structures can be thought of as the catalog of installed protocols. 


_ Applications can retrieve the contents of this catalog (see WSAEnumProtocols), and by 


examining the available WSAPROTOCOL_INFOW structures, discover the 
communications attributes associated with each protocol. 
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Layered Protocols and Protocol Chains in the SPI 


Windows Sockets 2 accommodates the notion of a layered protocol. A layered protocol 
is one that implements only higher level communications functions, while relying on an 
underlying transport stack for the actual exchange of data with a remote endpoint. An 
example of such a layered protocol would be a security layer that adds protocol to the 
connection establishment process in order to perform authentication and to establish a 
mutually agreed upon encryption scheme. Such a security protocol would generally 
require the services of an underlying reliable transport protocol such as TCP or SPX. 
The term base protocol refers to a protocol such as TCP or SPX which is fully capable of 
performing data communications with a remote endpoint, and the term /ayered protocol 
is used to describe a protocol that cannot stand alone. A protocol chain would then be 
defined as one or more layered protocols strung together and anchored by a base 
protocol. 


This stringing together of layered protocols and base protocols into chains can be 
accomplished by arranging for the layered protocols to support the Windows Sockets 2 
SPI at both their upper and lower edges. A special WSAPROTOCOL_INFOW structure 
is created, which refers to the protocol chain as a whole, and which describes the explicit 
order in which the layered protocols are joined. (See Figure 10-2.) 


API 
WS2_32.DLL 
SPI : 
Layered Protocol 
SPL. ———— 
Layered Protocol 
SPL 


Base Protocol 


Figure 10-2: Joining Layered Protocols. 
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Namespace Service Providers 


A namespace provider implements an interface mapping between the Windows 

Sockets 2 name space SPI and the native programmatic interface of an existing name 
service such as DNS, X.500, Netware® Directory Services (NDS), etc. While a name 
space provider supports exactly one name space, it is possible for multiple providers for 
a given name space to be installed. It is also possible for a single DLL to create an 
instance of multiple different name space providers. As name space providers are 
installed, a catalog of WSANAMESPACE_INFO structures is maintained. An application 
may use WSAEnumNameSpaceProviders to discover which name spaces are 
supported on a machine. Refer to Section Name Resolution Service Provider 
Requirements for detailed information. 


Legacy GetXbyY Service Providers 


Windows Sockets 2 fully supports the TCP/IP-specific name resolution facilities found in 
Windows Sockets version 1.1. It does this by including the set of GetXbyY functions in 
the SPI. However, the treatment of this set of functions is somewhat different from the 
rest of the SPI functions. The GetXbyY functions appearing in the SPI are prefaced with 
GETXBYYSP_, and are summarized as follows: 


Berkeley Style Functions 

SPI function name Description 

GETXBYYSP_gethostbyaddr Supply a hostent structure for the specified host 
address. | 

GETXBYYSP_gethostbyname | Supply a hostent structure for the specified host 
name. 

GETXBYYSP_getprotobyname Supply a protoent structure for the specified 


protocol name. 


GETXBYYSP_getprotobynumber Supply a protoent structure for the specified 
protocol number. 


GETXBYYSP_getservbyname Supply a servent structure for the specified 
| | | service nam.e 
GETXBYYSP_getservbyport Supply a servent structure for the service at the 
specified port. 
GETXBYYSP_gethostname Return the standard host name for the local 


machine. 
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Async Style Functions 


SPI function name | Description 

GETXBYYSP_WSAAsyncGetHostByAddr Supply a hostent structure for the 
| | specified host address. 

GETXBYYSP_WSAAsyncGetHostByName Supply a hostent structure for the 


) specified host name. 
GETXBYYSP_WSAAsyncGetProtoByName Supply a protoent structure for the 
, specified protocol name. 


GETXBYYSP_WSAAsyncGetProtoByNumber Supply a protoent structure for the 
| specified protocol number. 


GETXBYYSP_WSAAsyncGetServByName Supply a servent structure for the 
| specified service name. 
GETXBYYSP_WSAAsyncGetServByPort Supply a servent structure for the 
| | service at the specified port. 
GETXBYYSP_WSACancelAsyncRequest Cancel an asynchronous GetXbyY 


operation. 


The syntax and semantics of these GetXbyY functions are exactly the same as is 
documented in the Windows Sockets 2 API Specification and are, therefore, not 
repeated in this document. 


The Windows Sockets 2 DLL allows exactly one service provider to offer these services. 
Therefore, there is no need to include pointers to these functions in the procedure table 
received from service providers at startup . In 32-bit environments the path to the DLL 
that implements these functions is retrieved from the registry key named: 


Warning How the path is obtained in 16-bit environments has not yet been determined. 


Built-In Default GetXbyY Service Provider 


A default GetXbyY service provider is integrated into the standard Windows Sockets 2 
run-time components. This default provider implements all of the above functions, thus it 
is not required for these functions to be implemented by any name space provider. 
However, a name space provider is free to provide any or all of these functions (and thus 
override the defaults) by simply storing the string which is the path to the DLL that 
implements these functions in the indicated registry key. Any of the GetXbyY functions 
not exported by the named provider DLL will be supplied through the built-in defaults. 
Note, however, that if a provider elects to supply any of the async version of the 
GetXbyY functions, he should supply all of the async functions so that the cancel | 
operation will work appropriately. 7 
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For 32-bit environments, the current implementation of the default GetXbyY service 
provider resides within the Microsoft Wsock32.dll. Depending on how the TCP/IP 
settings have been established through Control Panel, name resolution will occur using 
either DNS or local host files. When DNS is used, the default GetXbyY service provider 
uses standard Windows Sockets 1.1 API calls to communicate with the DNS server. 
These transactions will occur using whatever TCP/IP stack is configured as the default 
TCP/IP stack. Two special cases however, deserve special mention. 


The default implementation of GETXBYYSP_gethostname obtains the local host name 
from the registry. This will correspond to the name assigned to “My Computer’. The 
default implementation of GETXBYYSP_gethostbyname and 
GETXBYYSP_WSAAsyncGetHostByName always compares the supplied host name 
with the local host name. If they match, the default implementation uses a private 
interface to probe the Microsoft TCP/IP stack in order to discover its local IP address. 


- Thus, in order to be completely independent of the Microsoft TCP/IP stack, a name 


space provider must implement both GETXBYYSP_gethostbyname and 
GETXBYYSP_WSAAsyncGetHostByName. 


Windows Sockets 2 Identifiers 


A Windows Sockets 2 clearinghouse has been established for service provider vendors 
to obtain unique identifiers for new address families, socket types, and protocols. FTP 
and world-wide web servers are used to supply current identifier/value mappings, and 
email is used to request allocation of new ones. At the time of this writing the world-wide 
web URL for the Windows Sockets 2 Identifier Clearinghouse is: 


http://www.stardust.com/winsock/ 


Data Transport Providers 


The following sections apply only to data transport service providers and the data 
transport portion of the SPI. 


Transport Division of Responsibilities Between DLL and Service 
Providers 


This section provides an overview of the division of responsibility between the 
Ws2_32.dll and transport service providers. 


Ws2_32.dll Functionality for Transport 


The major task of the data transport portion of the Ws2_32.dll is to serve as a sort of 
traffic manager between service providers and applications. Consider several different 
service providers interacting with the same application. Each service provider interacts 
strictly with the Ws2_32.dll. The Ws2_32.dll takes care of: 


e Selecting an appropriate service provider for creating sockets based on a protocol 
description. 
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e Forwarding application procedure calls involving a socket to the appropriate service 
provider that created or controls that socket. Service providers are unaware that any 
of this is happening. 


They do not need to be concerned about the details of cooperating with one another or 
even the existence of other service providers. By abstracting the service providers into a 
consistent DLL interface and performing this automatic traffic routing function, the 
Ws2_32.dll allows applications to interact with a variety of providers without requiring the 
applications to be aware of the divisions between providers, where different providers 
are installed. 7 


The Ws2_32.dll relies on the parameters of the API socket creation functions (socket 
and WSASocket) to determine which service provider to utilize. The selected transport 
service provider will be invoked through the WSPSocket function. In the case of the 
socket function, the Ws2_32.dll finds the first entry in the set of installed 
WSAPROTOCOL_INFOW siructures that matches the values supplied in the tuple 
formed by the (address family, socket type, protocol) parameters. To preserve backward 
compatibility, the Ws2_32.dll treats the value of zero for either address family or socket 
type as a wildcard value. The value of zero for protocol is not considered a wildcard 
value by the Ws2_32.dll unless such behavior is indicated for a particular protocol by 
having the PFL_MATCHES_PROTOCOL_ZERO flag Set in the 

WSAPROTOCOL_ INFOW structure. 


For the WSASocket function, if NULL i is supplied for JoProtocolInfo, the behavior is 
exactly as just described for socket. If a WSAPROTOCOL_INFO structure is 
referenced, however, the Ws2_32.dll does not perform any matching function but 
immediately relays the socket creation request to the transport service provider 
associated with the indicated WSAPROTOCOL_INFO structure. The values for the 
(address family, socket type, protocol) tuple are supplied intact to the service provider in 
the WSPSocket function. Service providers are free to ignore or pay attention to the 
values of the (address family, socket type, protocol) parameters as is appropriate, but 
they must not indicate an error condition when the value of either address family or 
socket type is zero. In addition, service providers must not indicate an error condition — 
when the manifest constant FROM_PROTOCOL_INFO is contained in any of the - 
(address family, socket type, protocol) parameters. This value simply indicates that the 
application wishes to use the values found in the corresponding parameters of the 
WSAPROTOCOL_INFO structure: (iAddressFamily, iSocketType, iProtocol). 


As part of socket creation a service provider informs the Ws2_32.dll about the 
association between itself and the new socket by means of parameters passed to 
WPUCreateSocketHandle or WPUModifylFSHandle. The Ws2_32.dll keeps track of 
this association between socket handles and particular service providers. Whenever an 
application interface function that refers to a socket handle is called, the Ws2_32.dll 
looks up the association and calls the corresponding service provider interface function 
of the appropriate service provider. 
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In addition to its major traffic routing service, the Ws2_32.dll provides a number of other 


services such as protocol enumeration, socket descriptor management (allocation, 


deallocation, and context value association) for nonfile-system service providers, 
blocking hook management on a per-thread basis, byte-swapping utilities, queuing of 
Asynchronous Procedure Calls (APCs) to facilitate invocation of I/O completion routines, 
and version negotiation between applications and the Ws2_32.dll, as well as between 
the Ws2_32.dll and service providers. 


Transport Service Provider Functionality 


Service providers implement the actual transport protocol which includes such functions 
as setting up connections, transferring data, exercising flow control and error control, etc. 
The Ws2_32.dll has no knowledge about how requests to service providers are realized; 
this is up to the service provider implementation. The implementation of such functions 
may differ greatly from one provider to another. Service providers hide the 
implementation-specific details of how network operations are accomplished. 


Transport service providers can be broadly divided into two categories: those whose 
socket descriptors are real file system handles (and are hereafter referred to as 
Installable File System (IFS) providers; the remainder are referred to as non-IFS 
providers. The Ws2_32.dll always passes the transport service provider's socket 
descriptor on up to the Windows Sockets application, so applications are free to take 
advantage of socket descriptors that are file system handles if they so choose. 


To summarize: Service providers implement the low-level network-specific protocols. 
The Ws2_32.dll provides the medium-level traffic management that interconnects these 
transport protocols with applications. Applications in turn provide the policy of how these 
traffic streams and network-specific operations are used to accomplish the functions 
desired by the user. 


Transport Mapping Between API and SPI Functions 

The Windows Sockets Transport SPI is similar to the Windows Sockets API in that all of 
the basic socket functions appear. When a new Windows Sockets 2 version of a function 
and the original Windows Sockets 1.1 version of a function both exist in the API, only the 
new version will show up in the SPI. For example: 

® connect and WSAConnect both map to WSPConnect 

e accept and WSAAccept map to WSPAccept 

e socket and WSASocket map to WSPSocket 


Other API functions that are collapsed into the enhanced versions in SPI include: 
° send | | 

° sendto 

e recv 

e recvfrom 

e joctisocket 
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Support functions like htonl, htons, ntohl, and ntohs are implemented in the 
Ws2_32.dll, and are not passed down to service providers. The same holds true for the 
WSA versions of these functions. 


Windows Sockets service provider enumeration and the blocking hook-related functions 
are realized in the Ws2_32.dll, thus WSAEnumProtocols, WSAIsBlocking, 
WSASetBlockingHook, and WSAUnhookBlockingHook do not appear as SPI 
functions. 


Since error codes are returned along with SPI functions, equivalents of 
WSAGetLastError and WSASetLastError are not needed in the SPI. 


The event object manipulation and wait functions including WSACreateEvent, 
WSACloseEvent, WSASetEvent, WSAResetEvent, and WSAWaitForMultipleEvents 
are mapped directly to native OS services and thus are not present in the SPI. 


All the TCP/IP-specific name conversion and resolution functions in Windows Sockets 
1.1 such as getXbyY, WSAAsyncGetXByY and WSACancelAsyncRequest, as well as 
_gethostname are implemented within the Ws2_32.dll in terms of the new name 

_ resolution facilities. See Windows Sockets 1.1 Compatible Name Resolution for TCP/IP 

- for details. Conversion functions such as inet_addr and inet_ntoa are implemented 
within the Ws2_32.dll. : 


Function Extension Mechanism i in the SPI 


Since the Windows Sockets DLL itself is no longer supplied by each individual stack | 
vendor, it is no longer possible for a stack vendor to offer extended functionality by just 
adding entry points to the Windows Sockets DLL. To overcome this limitation, Windows 
Sockets 2 takes advantage of the new WSAloctl function to accommodate service 
providers who wish to offer provider- -specific functionality extensions. This mechanism 
presupposes, of course, that an application is aware of a particular extension and 
understands both the semantics and syntax involved. Such information would typically — 
be supplied by the service provider vendor. 


In order to invoke an extension function, the application must first ask for a pointer to the 
desired function. This is done through the WSAloctl function using the 
SIO_GET_EXTENSION_FUNCTION_POINTER command code. The input buffer to the 
WSAloctl function contains an identifier for the desired extension function and the 
output buffer will contain the function pointer itself. The application can then invoke the 
extension function directly without passing through the Ws2_32.dll. 


The identifiers assigned to extension functions are globally unique identifiers (GUIDs) 
that are allocated by service provider vendors. Vendors who create extension functions — 
are urged to publish full details about the function including the syntax of the function 
prototype. This makes it possible for common and/or popular extension functions to be 
offered by more than one service provider. An application can obtain the function pointer 
and use the function without needing to know anyinng about the ¢ particular service 
provider that implements the function. 


fun = ae : 
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Transport Configuration and Installation 


In order for a transport protocol to be accessible through Windows Sockets it must be 
properly installed on the system and registered with Windows Sockets. When a transport 
service provider is installed by invoking a vendor's installation program, configuration 
information must be added to a configuration database to give the Ws2_32.dll required 
information regarding the service provider. The Ws2_32.dll exports an installation 
function, WSCinstallProvider for the vendor’s installation program to supply the relevant 
information about the to-be-installed service provider, for example, the name and path to 
the service provider DLL and a list of WSAPROTOCOL_INFOW structures that this 
provider can support. Symmetrically, the Ws2_32.dll also provides a function, 
WSCDeinstallProvider, for a vendor's deinstallation program to remove all the relevant 
information from the configuration database maintained by the Ws2_32.dll. The exact 
location and format of this configuration information is private to the Ws2_32.dll, and can 
only be manipulated by the above-mentioned functions. 


The order in which transport service providers are initially installed governs the order in 
which they are enumerated through WSCEnumProtocols at the service provider 
interface, or through WSAEnumProtocols at the application interface. More importantly, 


this order also governs the order in which protocols and service providers are considered 


when a client requests creation of a socket based on its address family, type, and 
protocol identifier. Windows Sockets 2 includes an applet called Sporder.exe that allows 
the catalog of installed protocols to be re-ordered interactively after protocols have 
already been installed. Windows Sockets 2 also includes an auxiliary DLL, Sporder.dll, 
that exports a procedural interface for re-ordering protocols. This procedural interface is 
described in Service Provider Ordering. 


Installing Layered Protocols and Protocol Chains 

The WSAPROTOCOL_INFO structure supplied with each protocol to be installed 
indicates whether the protocol is a base protocol, layered protocol, or protocol chain. The 
value of the ProtocolChain.ChainLen parameter is interpreted as shown in the following 
table. : 


Value Meaning 

0 | Layered protocol. 

1 | Base protocol (or chain with only one component). 
>1 Protocol chain. 


Installation of protocol chains can only occur after successful installation of all of the 
constituent components (base protocols and layered protocols). The 
WSAPROTOCOL_INFOW structure for a protocol chain uses the ProtocolChain 


_ parameter to describe the length of the chain and the identity of each component. The 


individual protocols that make up a chain are listed in order in the | 
ProtocolChain.ChainEntries array, with the zeroth element of the array corresponding to 
the first layered provider. Protocols are identified by their CatalogEntry!D values, which 
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are assigned by the Ws2_32.dll at protocol installation time, and can be found in the 
WSAPROTOCOL_INFOW structure for each protocol. 


The values for the remaining parameters in the protocol chain’s 
WSAPROTOCOL_INFOW structure should be chosen to reflect the attributes and 
identifiers that best characterize the protocol chain as a whole. When selecting these 
values, developers should bear in mind that communications over protocol chains can 
only occur when both endpoints have compatible protocol chains installed, and that 
applications must be able to recognize the corresponding WSAPROTOCOL_INFO 
structure. 


When a base protocol is installed, it is not necessary to make any entries in the 
Protoco!Chain.ChainEntries array. It is implicitly understood that the sole component of 
this chain is already identified in the CatalogEntryID parameter of the same 
WSAPROTOCOL_INFO structure. Also note that protocol chains may not include 
multiple instances of the same layered protocol. 


Name Resolution Providers 


The following sections apply only to name resolution service providers and the n name 
| resolution portion of the SPI. 


Name Resolution Model for the SPI — 


In developing a protocol- independent client/server application, there are two basic 
requirements that exist with respect to name resolution and registration: 


e The ability of the server half of the application (hereafter referred to as a service) to 
register its existence within (or become accessible to) one or more name spaces. 


e The ability of the client application to find the service within a name space and obtain 
the required transport protocol and addressing information. 


For those accustomed to developing TCP/IP based applications, this may seem to 
involve little more than looking up a host address and then using an agreed upon port 
number. Other networking schemes, however, allow the location of the service, the 
protocol used for the service, and other attributes to be discovered at run-time. To 
accommodate the broad diversity of capabilities found in existing name services, the 
Windows Sockets 2 interface adopts the model described below. 


A namespace refers to some capability to associate (as a minimum) the protocol and 
addressing attributes of a network service with one or more human-friendly names. 
-Many name spaces are currently in wide use including the Internet's Domain Name 
System (DNS), Netware Directory Services (NDS), X.500, etc. These name spaces vary 
widely in how they are organized and implemented. Some of their properties are 
particularly important to understand from the perspective of Windows Sockets name 
resolution. 
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Types of Namespaces in the SPI 
There are three different types of namespaces in which a service could be registered: 


e Dynamic 
e Static 
e Persistent 


Dynamic namespaces allow services to register with the name space on the fly, and for 
clients to discover the available services at run time. Dynamic name spaces frequently 
rely on broadcasts to indicate the continued availability of a network service. Examples 
of dynamic name spaces include the SAP name space used within a Netware 
environment and the NBP name space used by Appletalk®. 


Static name spaces require all of the services to be registered ahead of time, that is, 
when the name space is created. The DNS is an example of a static name space. 
Although there is a programmatic way to resolve names, there is no programmatic way 
to register names. 


Persistent name spaces allow services to register with the name space on the fly. Unlike 
dynamic name spaces however, persistent name spaces retain the registration 
information in nonvolatile storage where it remains until such time as the service | 
requests that it be removed. Persistent name spaces are typified by directory services 


_ such as X.500 and the NDS (Netware Directory Service). These environments allow the 


adding, deleting, and modification of service properties. In addition, the service object 
representing the service within the directory service could have a variety of attributes 

associated with the service. The most important attribute for client applications is the 

service’s addressing information. 


Namespace Organization in the SPI 


Many namespaces are arranged hierarchically. Some, such as X.500 and NDS, allow 
unlimited nesting. Others allow services to be combined into a single level of hierarchy or 
group. This is typically referred to as a workgroup. When constructing a query, it is often 
necessary to establish a context point within a namespace hierarchy from which the 
search will begin. 


Namespace Provider Architecture in the SPI 

Naturally, the programmatic interfaces used to query the various types of name spaces 
and to register information within a namespace (if supported) differ widely. A namespace 
provider is a locally-resident piece of software that knows how to map between the 


Windows Sockets namespace SPI and some existing namespace (which could be 


implemented ocany or accessed iia the nemwolK): This is shown in egue 10-3. 


Note Note that it is possible for a given namespace, say DNS, to have more than one 


namespace provider installed on a given machine. 
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Figure 10-3: Namespace Provider. 


As mentioned above, the generic term service refers to the server-half of a client/server 
application. In Windows Sockets, a service is associated with a service class, and each 
instance of a particular service has a service name which must be unique within the 
service class. Examples of service classes include FTP Server, SQL Server, XYZ Corp. 
Employee Info Server, etc. 


As the example attempts to illustrate, some service classes are well Known while others 
are very unique and specific to a particular vertical application. In either case, every 
service class is represented by both a class name and a class identifier. The class name 
does not necessarily need to be unique, but the class identifier must be. Globally Unique 
Identifiers (GUIDs) are used to represent service class IDs. For well-known services, 
class names, and class identifiers (GUIDs) have been pre-allocated, and macros are 
available to convert between, for example, TCP port numbers and the corresponding 
class identifier GUIDs. For other services, the developer chooses the class name and 
uses the Uuidgen.exe utility to generate a GUID for the class identifier. 


The notion of a service class exists to allow a set of attributes to be established that are 
held in common by all instances of a particular service. This set of attributes is supplied 
to Windows Sockets at the time the service class is defined, and is referred to as the 
service class schema information. The Ws2_32.dll in turn relays this information to all 
active name space providers. When an instance of a service is installed and made 
available on a host machine, its service name is used to distinguish this particular 
instance from others that may be known to the name space. 


Note that the installation of a service class only needs to occur on machines where the 
service executes, not on all of the clients which may utilize the service. Where possible, 
the Ws2_32.dll will provide service class schema information to a name space provider 
at the time an instance of a service is to be registered or a service query is initiated. The 
Ws2_32.dll does not, of course, store this information itself, but attempts to retrieve it 
from a name space provider that has indicated its ability to supply this data. Since there - 
is no guarantee that the Ws2_32.dll will be able to supply the service class schema, 
name space providers that need this information must have a fallback mechanism to 
obtain it through name space-specific means. 
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The Internet's Domain Name System does not have a well-defined means to store 
service class schema information. As a result, DNS name space providers will only be 
able to accommodate well-known TCP/IP services for which a service class GUID has 
been preallocated. In practice, this is not a serious limitation since service class GUIDs 
have been preallocated for the entire set of TCP and UDP ports, and macros are 


— available to retrieve the GUID associated with any TCP or UDP port. Thus, all of the 


familiar services such as ftp, telnet, whois, etc. are well supported. When querying for 
these services, by convention the host name of the target machine is the service 
instance name. 


Continuing with our service class example, instance names of the ftp service may be 
“alder.intel.com” or “rhino.microsoft.com” while an instance of the XYZ Corp. Employee 
Info Server might be named “XYZ Corp. Employee Info Server Version 3.5”. In the first 
two cases, the combination of the service class GUID for ftp and the machine name 
(supplied as the service instance name) uniquely identify the desired service. In the third 
case, the host name where the service resides can be discovered at service query time, 
so the service instance name does not need to include a host name. 


Name Resolution Division of Responsibilities Between DLL and 
Service Providers 


The following paragraphs describe how the Ws2_32.dll and the name space providers 
cooperate together to implement the name resolution services supported by the 
Windows Sockets 2 API. 


Ws2_32.dll Functionality for Name Resolution 


The Ws2_32.dll manages the registration and demand loading of individual name space 
provider DLLs. It also is responsible for routing name space operations from a Windows 
Sockets 2 application to the appropriate set of name space providers. This mapping is 
governed by the value of name space and service provider identifier parameters that are 
found in individual API functions. As a general rule, when a specific name space 
provider is referenced, the operation is only routed to an identified provider. If the name 
space provider identifier is NULL but a particular name space is referenced, the 
operation is routed to all name space providers that support the identified name space. If 
the name space provider identifier is NULL and the name space identifier is given as 
NS_ALL, then the operation is routed to all active name space providers. 


As part of starting a query to one or more service providers, the Ws2_32.dll allocates an 
object to keep track of the ongoing state of the query. An opaque handle representing 
this object is returned to the application that started the query. The application supplies 
this handle as a parameter each time it repetitively calls an application interface function 
to retrieve the next unit of data resulting from the query. 


In response to these application interface procedure calls, the Ws2_32.dll uses the 
information it stores in the object to make corresponding calls to the name space 
providers involved in the query. The Ws2_32.dIl updates the information in its object as 
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each successive application interface call occurs so that the corresponding calls to name 
space providers progress appropriately through all of the name space providers involved 
in the query. 


Name Space Provider Functionality 


Each name space provider is responsible for mapping the set of functions appearing in 
the Windows Sockets 2 name resolution SPI to the appropriate transactions with the 
supported name space. In some cases, this is primarily a matter of mapping the SPI to 
whatever native interface exists for the name space. In others, the name space provider 
must conduct transactions with the name space provider over the network. Some name 
space providers will do this by making calls to the Windows Sockets API, others will use 
private interfaces to associated transport stacks. 


Name Resolution Mapping Between API and SPI Functions 


The installation of service classes, registration of service instances and basic query 
operations all map fairly directly from the API to the SPI. The 
WSAGetServiceClassNameByClassld function does not have a corresponding 
function in the SPI, as this function is implemented in Ws2_32.dll by making a call to 
NSPGetServiceClassinfo. | _ 


The helper functions WSAAddressToString and WSAStringToAddress are mapped to 
the corresponding functions in the transport API, as only a transport provider will 
necessarily know how to perform the translation on a SOCKADDR structure. 


Name Resolution Configuration and Installation 


In order for a name space provider to be accessible through Windows Sockets it must be 
properly installed on the system and registered with Windows Sockets. When a name 
space provider is installed by invoking a vendor's installation program, configuration | 
information must be added to a configuration database to give the Ws2_32.dll required 
information regarding the service provider. The Ws2_32.dll exports 
WSCinstallNameSpace for the vendor's installation program to use. This function is 
used to supply relevant information about the to-be-installed service provider. This 
information includes: 


e Provider Name - A string representing the provider for display in Control Panel 
e Provider Version - The version of this provider 

e Provider Path - A path name to the provider DLL 

e Name Space - The name space supported by the provider 


—@ Provider GUID - A unique, vendor-supplied number representing this provider/name 
Space combination. This is used as a key for all subsequent references to this 
provider, and for uninstall. These values are created using the Uuidgen.exe utility. 
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e Stores all flag - a flag indicating whether this name space provider will be responsible 
for retaining all service class schema information for all service classes. If sucha 
provider exists, the Ws2_32.dll does not need to query each individual name space 
provider for this information. 


Symmetrically, the Ws2_32.dll also provides a function, WSCUnInstaliNameSpace, for 
a vendor’s deinstallation program to remove all the relevant information from the 
configuration database. The exact location and format of this configuration information is 
private to the Ws2_32.dll, and can only be manipulated by the above-mentioned 
functions. 


At any point, an NSP is considered to be either active or inactive, with this setting 
controlled through the WSCEnableNSProvider function. Name space providers that are 
inactive continue to show up when enumerated through 
WSAEnumNameSpaceProviders, but the Ws2_32.dll will not route any query or 
service registration operations to these providers. This capability can be useful in 
situations where more than one of the installed name space providers can support a 
given name space. 


When multiple name space providers are referenced in a single API function, the order in 
which the order in which the queries and registration operations are routed to name 
space providers is unspecified. The order is unrelated to the order in which name space 
providers are installed. There are two ways to control which name space providers are 
used to resolve a name query. First, the name space configuration function, 
WSCEnableNSProvider can be used to enable and disable name spaces in a machine- 
wide, persistent way. Second, applications can direct an individual query to a particular 
provider by specifying that provider’s identifying GUID as part of the query. 


Windows Sockets 2 Transport Provider Requirements 


The following sections provide a description of each of the functional areas which 
transport service providers are required to implement. Where appropriate, 
implementation considerations and guidelines are also provided. 


Service Provider Activation 


The following sections describe the sequence of events involved in bringing a transport 
service provider DLL into memory, initializing it, and eventually, de-initializing it. 


Initialization 


The Ws2_32.dll loads the service provider's interface DLL into the system by using the 
standard Microsoft® Windows® dynamic library loading mechanisms, and initializes it by 
calling WSPStartup. This is usually triggered by an application calling either socket or 
WSASocket in order to create a new socket that is to be associated with a service 
provider whose interface DLL is not currently loaded into memory. The path to each 


Chapter 10 Winsock 2 SPI Overview 435 


service provider's interface DLL is stored by the Ws2_32.dll at the time the service 
provider is being installed. See section Configuration and Installation for more 
information. 


Over time, different versions may exist for the Windows Sockets 2 DLLs, applications, 
and service providers. New versions may define new features, new parameters to data 
structures and bit parameters, etc. Version numbers therefore indicate how to interpret 
various data structures. 


To allow optimal mixing and matching of different versions of applications, versions of 
the Ws2_32.dll itself, and versions of service providers by different vendors, the SPI 
provides a version negotiation mechanism for use between the Ws2_32.dll and the 
service providers. This version negotiation is handled by WSPStartup. Basically, the 
Ws2_32.dll passes to the service provider the highest version numbers with which it is 
compatible. The service provider compares this with its own supported range of version 
numbers. If these ranges overlap, the service provider returns a value within the 
overlapping portion of the range as the result of the negotiation. Usually, this should be 
the highest possible value. If the ranges do not overlap, the two parties are incompatible 
and the function returns an error. 


WSPStartup must be called at least once by each client process, and may be called 
multiple times by Ws2_32.dll or other entities. A matching WSPCleanup must be called 
for each successful WSPStartup call. The service provider should maintain a reference 
count on a per-process basis. On each WSPStartup call, the caller may specify any 
version number supported by the SP DLL. 


A service provider must store the pointer to the client’s upcall dispatch table that is 
received as a WSPStartup parameter on a per-process basis. If a given process calls 
WSPStartup multiple times, the service provider must use only the most recently | 
supplied dispatch table pointer. 


As part of the service provider initialization process The Ws2_32.dll retrieves the service 
provider's dispatch table through the /pProcTable parameter in order to obtain entry 
points to the rest of the SPI functions specified in this document. 


Using a dispatch table (as opposed to the usual DLL mechanisms for ans entry 
points) serves two purposes: 


e It is more convenient for the Ws2_32.dll since a single call can be made to discover 
the entire set of entry points. 


e It enables layered service providers formed into protocol chains to operate more 
efficiently. 3 


Initializing Protocol Chains 


At the time the WSAPROTOCOL_INFOW structure for a protocol chain is installed, the 
path to the first layered provider in the chain is also specified. When a protocol chain is 
initialized, the Ws2_32.dll uses this path to load the provider DLL and then invokes 
WSPStartup. Since WSPStartup includes a pointer to the chain’s 
WSAPROTOCOL_INFOW structure as one of its parameters, layered providers can 
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determine what type of chain they are being initialized into, and the identity of the next 
lower layer in the chain. A layered provider would then in turn load the next protocol 
provider in the chain and initialize it with a call to WSPStartup, and so forth. Whenever 
the next lower layer is another layered provider, the chain's WSAPROTOCOL_INFOW 
structure must be referenced in the WSPStartup call. When the next lower layer is a 
base protocol (signifying the end of the chain), the chain's WSAPROTOCOL_INFOW 
structure is no longer propagated downward. Instead, the current layer must reference a 
WSAPROTOCOL_INFOW structure that corresponds to the protocol that the base 
provider should use. Thus, the base provider has no notion of being involved in a 
protocol chain. 


The dispatch table provided by any given layered provider will, in many instances, 
duplicate the entry points of an underlying provider. The layered provider would only 
insert its own entry points for functions that it needed to be directly involved in. Note, 
however, that it is imperative that a layered provider not modify the contents of the 
upcall table that it received when calling WSPStartup on the next lower layer in a 
protocol chain. These upcalls must be made directly to the Windows Sockets 2 DLL. 


Cleanup 


The Ws2_32.dll (and layered protocols) will call WSPCleanup once for each invocation 
of WSPStartup. On each invocation, WSPCleanup should decrement a per-process 
reference counter, and when the counter reaches zero the service provider must prepare 
itself to be unloaded from memory. The first order of business is to finish transmitting any 
unsent data on sockets that are configured for a graceful close. Thereafter, any and all 
resources held by the provider are to be freed. The service provider must be left in a 
state where it can be immediately re-initialized by a call to WSPStartup. 


PITOr Reporting and Parameter Validation 


The scheme for error reporting differs between the SPI and API interfaces. Windows 
Sockets service providers report errors along with the function returning, as opposed to 
the per-thread based approach utilized in the API. The Ws2_32.dll uses the service 
provider’s per-function error code to update the per-thread error value that is obtained 
through the WSAGetLastError API function. Service providers are still required, 
however, to maintain the per-socket based error which can be retrieved through the 
SO_ERROR socket option. 


The Ws2_32.dll performs parameter validation only on function calls that are 
implemented entirely within itself. Service providers are responsible for performing all of 
their own parameter validation. 


Byte Ordering Assumptions 


A service provider should treat all SOCKADDR components exclusive of the address 
family parameter as if they are in the network byte order, and the address family 
parameter as in the local machine’s byte order. It is the Windows Sockets application’s 
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responsibility to make sure that addresses contained in SOCKADDR structures are 
properly arranged. The Windows Sockets API provides a number of conversion routines 
to simplify this task. Currently these routines understand conversion between the local 
host’s natural byte order and either big-endian or little-endian network byte ordering. The 
Windows Sockets architecture can support other byte ordering schemes in the future. 


Socket Creation and Descriptor Management 


The following sections describe aspects of creating new sockets and the allocation of 
socket descriptors. 


Descriptor Allocation 


While Windows Sockets service providers are encouraged to implement sockets as 
installable file system (IFS) objects, the Windows Sockets architecture also 
accommodates service providers whose socket handles are not IFS objects. Providers 
with IFS handles indicate this through the XP1_IFS_HANDLES attribute bit in the 
WSAPROTOCOL_INFOW structure. (Note: the XP1_IFS_HANDLES attribute bit was 
not included in release 2.0.8 of the API specification, but has since been added through 
the errata mechanism.) Windows Sockets SPI clients may take advantage of providers 
whose socket descriptors are IFS handles by using these descriptors with standard 
Win32 I/O facilities, such as ReadFile and WriteFile. — 


Whenever an IFS provider creates a new socket descriptor, itis mandatorythatthe _ 
provider call WPUModifylFSHandle prior to supplying the new handle toa Windows 
Sockets SPI client. This function takes a provider identifier and a proposed IFS handle 
from the provider as input and returns a (possibly) modified handle. The IFS provider 
must supply only the modified handle to its client, and all requests from the client will 
reference only this modified handle. The modified handle is guaranteed to be 
indistinguishable from the proposed handle as far as the operating system is concerned. 
Thus in most instances, the service provider will simply choose to use only the modified 
handle in all of its internal processing. The purpose of this modification function is to 
allow the Ws2_32.dll to greatly streamline the process of identifying the service provider 
associated with a given socket. 


Providers that do not return IFS handles must obtain a valid handle from the Ws2_32.dll 
via the WPUCreateSocketHandle call. The nonIFS provider must offer only a Windows 
Sockets 2.dll-supplied handle to its client, and all requests from the client will reference 
only these handles. As a convenience to service provider implementers, one of the input 

parameters supplied by a provider in WPUCreateSocketHandle is a DWORD context 
value. The Ws2_32.dll associates this context value with the allocated socket handle 
and allows a service provider to retrieve the context value at any time through the 
WPUQuerySocketHandleContext call. A typical use for this context value would be to — 
store a pointer to a service provider maintained data structure used to store socket state 
Information. : 7 
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Socket Attribute Flags and Modes 


There are several socket attributes which can be indicated through the flags parameter 
in WSPSocket. The WSA_FLAG_OVERLAPPED flag indicates that a socket will be 
used for overlapped I/O operations. Support of this attribute is mandatory for all service 
providers. See Overlapped I/O for more information. Note that creating a socket with the 
overlapped attribute has no impact on whether a socket is currently in the blocking or 
nonblocking mode. Sockets created with the overlapped attribute may be used to 
perform overlapped I/O, and doing so does not change the blocking mode of a socket. 
Since overlapped I/O operations do not block, the blocking mode of a socket is irrelevant 
for these operations. 


Four additional attribute flags are used when creating sockets that are to be used for 
multipoint and/or multicast operations, and support for these attributes is optional. 
Providers that support multipoint attributes indicate this through the 
XP1_SUPPPORT_MULTIPOINT bit in their respective WSAPROTOCOL_INFOW 
structures. See WSPSocket and section Protocol-Independent Multicast and Multipoint 
in the API for the definition and usage of each of these flags. Only sockets that are 
created with multipoint-related attributes can be used in the WSPJoinLeaf function for 
creating multipoint sessions. 


A socket is in one of two modes, blocking and nonblocking, at any time. Sockets are 
created in the blocking mode by default, and can be changed to nonblocking mode by 
calling WSPAsyncSelect, WSPEventSelect, or WSPloctl. A socket can be switched 
back to blocking mode by using WSPloctl if no WSPAsyncSelect or WSPEventSelect 
is active. The mode for a socket only affects those functions which may block, and does 
not affect overlapped I/O operations. See section Blocking Operations for more 
information. 


Closing Sockets 


WSPCloseSocket releases the socket descriptor so that any pending operations in any 
threads of the same process will be aborted, and any further reference to it will fail. Note 
that a reference count should be employed for shared sockets, and only if this is the last 
reference to an underlying socket, should the information associated with this socket be 
discarded, provided graceful close is not requested (that is, SO_DONTLINGER is not 
set). In the case of SO_DONTLINGER being set, any data queued for transmission will 
be sent, if possible, before information associated with the socket is released. See 
WSPCloseSocket for more information. 


For nonlFS service providers, WPUCloseSocketHandle must be invoked to release the 
socket handle back to the Windows Sockets 2 DLL. 


Blocking Operations 


The notion of blocking in a Windows environment has historically been a very important 
one. In Windows Sockets 1.1 environments, blocking calls were discouraged since they 
tend to disable ongoing interaction with the Windowing system, and since they employ a 
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pseudo blocking technique which, for a variety of reasons, does not always work as 
intended. However, in preemptively scheduled Win32 environments such as 

Windows 95/98® and Windows NT®/Windows® 2000, blocking calls make much more 
sense, can be implemented by native operating system services, and are in facta 
generally preferred mechanism. The Windows Sockets 2 API no longer supports psuedo 
blocking, but because the Windows Sockets 1.1 compatibility shims must continue to 
emulate this behavior, service providers must support this as described below. 


Pseudo vs. True Blocking 


In 16 Windows environments, true blocking is not supported by the OS, thus a blocking 
operation that cannot be completed immediately is handled as follows: 


e The service provider initiates the operation, and then enters a loop during which it 
dispatches any Windows messages (yielding the processor to another thread if 
necessary) 


e |t then checks for the completion of the Windows Sockets function. 


e lf the function has completed, or if WSPCancelBlockingCall has been invoked, the 
loop is terminated and the blocking function completes with an appropriate result. 


This is what is meant by the term pseudo blocking, and the loop referred to above is 
known as the default blocking hook. 


Blocking Hook 


Although this mechanism is sufficient for simple applications, it cannot support the 
complex message-dispatching requirements of more advanced applications such as 
those using the Multiple Document Interface (MDI) model. For such applications, a 
thread-specific blocking hook may be installed by the application. This will be called by 
the service provider instead of the default blocking hook described above. A service 
provider must retrieve a pointer to the per-thread blocking hook from the Ws2_32.dll by 
calling WPUQueryBlockingCallback. If the application has not installed its own 
blocking hook a pointer to the default blocking hook function will be returned. 


A Windows Sockets service provider cannot assume that an application-supplied 
blocking hook allows message processing to continue as the default blocking hook does. 
Some applications cannot tolerate the possibility of reentrant messages while a blocking 
operation is outstanding. Such an application’s blocking hook function would simply 
return FALSE. If a service provider depends on messages for its internal operation, it 
may execute PeekMessage(hMyWnd...) before executing the application’s blocking 
hook so that it can get its own messages without affecting the rest of the system. 


There is no default blocking hook installed in preemptive multithreaded versions of 
Windows. This is because other processes will not be blocked if a single application is 
waiting for an operation to complete (and hence not calling PeekMessage or 
GetMessage which causes the application to yield the processor in nonpreemptive 
Windows). When the service provider calls WPUQueryBlockingCallback a null pointer 
will be returned indicating that the provider is to use native OS blocking functions. 
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However, in order to preserve backward compatibility, an application-supplied blocking 
hook can still be installed on a per-thread basis in 32 bit versions of Windows. 


The Windows Sockets service provider calls the blocking hook only if all of the following 
are true: the routine is one which is defined as being able to block, the specified socket 
is a blocking socket, and the request cannot be completed immediately. If only 
nonblocking sockets and WSPAsyncSelect/WSPEventSelect instead of WSPSelect 
are used, then the blocking hook will never be called. 


Important If, during the time pseudo blocking is being used to block a thread, a 
Windows message is received for the thread, there is a risk that the thread will attempt to 
issue another Windows Sockets call. Because of the difficulty of managing this condition 
safely, the Windows Sockets 1.1 specification disallowed this behavior. It is not 
permissible for a given thread to make multiple nested Windows Sockets function calls. 
Only one outstanding function call is allowed for a particular thread. Any nested 
Windows Sockets function calls fail with the error WSAEINPROGRESS. It should be 
emphasized that this restriction applies to both blocking and nonblocking operations, but 
only in Windows Sockets 1.1 environments. There are a few exceptions to this rule, 
including two functions that allow an application to determine whether a pseudo blocking 
operation is in fact in progress, and to cancel such an operation if need be. These are 
described below. 


Canceling Blocking Operations 


A thread may, at any time, call WSAlsBlocking to determine whether or not a blocking 
call is currently in progress. (This function is implemented within the Windows Sockets 
1.1 compatibility shims and hence has no SPI counterpart.) Clearly this is only possible 
when pseudo blocking, as opposed to true blocking, is being employed by the service 
provider. When necessary, WSPCancelBlockingCall may be called at any time to 
cancel any current pseudo blocking operation. 


Objects in the Windows Sockets 2 SPI 


Event objects are introduced in Windows Sockets 2 as a general synchronization 
mechanism between Windows Sockets 2 service providers and applications. They are 
used for a number of purposes including indicating the completion of overlapped 
operations and the occurrence of one or more network events. | 


Creating Event Objects 


The Ws2_32.dll provides facilities for event object creation to both applications and 
service providers, although in most instances event objects will be created by 
applications. Event object services are made available to Windows Sockets service 
providers through WPUCreateEvent simply as a convenience mechanism for any 
internal processing that may benefit from same. Note that the event object handle is only 
valid in the context of the calling process. In Win32 environments the realization of event 
objects is through the native event services provided by the operating system. 
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Using Event Objects 

Windows Sockets event objects are fairly simple constructs which can be created and 
closed, set and cleared, waited upon and polled. The general usage model is for clients 
to create an event object and supply the handle as a parameter (or as a component of a 
parameter structure) in functions such as WSPSend and WSPEventSelect. When the 
nominated condition has occurred, the service provider uses the handle to set the event 
object by calling WPUSetEvent. Meanwhile, the Windows Sockets SPI client may either 
block and wait or poll until the event object becomes set (or as it is sometimes called: 
signaled). The client may subsequently clear or reset the event object and use it again. 


Destroying Event Objects 


The entity which creates an event object (application or service provider) is responsible 
for destroying it when it is no longer required. Service providers do this through 
WPUCloseE vent. 


Notification of Network Events 


One of the most important responsibilities of a data transport service provider is that of 
providing indications to the client when certain network events have occurred. The list of 
defined network events consists of the following: 


e FD_CONNECT - A connection to a remote host or to a multicast session has been 
completed 

e FD_ACCEPT - A remote host is making a connection request 

~@ FD_READ - Network data has arrived which is available to be read 

e FD_WRITE - Space has become available in the service provider's buffers so that 
additional data may now be sent 

e FD_OOB - Out of band data is available to be read 

e FD_CLOSE - The remote host has closed down the connection 

e FD_QOS - Achange has occurred in negotiated QOS levels 

e FD_GROUP_QOS - Reserved. 

e FD_ROUTING_INTERFACE_CHANGE -— A local interface that should be used to 
reach the destination specified in SIO_ROUTING_INTERFACE_CHANGE IOCLT has 
changed 

e FD_ADDRESS_LIST_CHANGE - The list of local addresses to which application can 
bind has changed 


The set of network events enumerated above is sometimes referred to as the FD_XXX 
events. Indication of the occurrence of one or more of such network events may be given 
in a number of ways depending on how the client requests for notification. | 
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Selects 


In the original BSD sockets interface the select call was the standard (and only) means 
to obtain network event indications. For each socket, information on read, write, or error 
status can be polled or waited on. See WSPSelect for more information. Note that 
network event FD_QOS and cannot be obtained by this approach. 


Windows Messages 


Windows Sockets 1.1 introduced the async-select mechanism in order to provide 
network event indications in a manner that did not involve either polling or blocking. The 
WSPAsyncSelect function is used to register an interest in one or more network events 
as listed above, and supply a window handle to be used for notification. When a 
nominated network event occurs, a client-specified Windows message is sent to the 
indicated window. The service provider must use the WPUPostMessage function to 
accomplish this. 


In Win32 environments, this may not be the most efficient notification mechanism, and is 
inconvenient for daemons and services that don’t want to open any windows. The event 
object signaling mechanism described below is introduced to solve this problem. 


Event Object Signaling 


WSPEventSelect behaves exactly like WSPAsyncSelect except that, rather than cause 
a Windows message to be sent on the occurrence of any nominated FD_XXX network 
event (for example, FD_READ, FD_WRITE, etc.), a designated event object is set. 


Also, the fact that a particular FD_XXX network event has occurred is remembered by 
the service provider. This is needed since the occurrence of any and all nominated 
network events will result in a single event object becoming signaled. A call to 
WSPEnumNetworkEvents causes the current contents of the network event memory to 
be copied to a client-supplied buffer and the network event memory to be cleared. The 
client may also designate a particular event object to be cleared atomically along with 
the network event memory. 


socket Groups in the Windows Sockets 2 SPI 


All use of Socket Groups is reserved. 


Socket Group Operations 


All use of Socket Groups is reserved. 


Required Socket Grouping Behavior 
All use of Socket Groups is reserved. 


Recommended Socket Grouping Behavior 


All use of Socket Groups is reserved. 
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Quality of Service in the Windows Sockets 2 SPI 


Quality of Service is implemented in Windows 2000 through various Windows 2000 QOS 
components. For details and implementation guidelines, see the QOS chapters later in 
this book. 


Socket Connections on Connection-Oriented Protocols 


The following paragraphs describe the semantics applicable to socket connections over 
connection-oriented protocols. 


Binding to a Local Address 


Before a socket can be used to set up a connection or receive a connection request, it 
needs to be bound to a local address. This could be done explicitly by calling WSPBind, 
or implicitly by WSPConnect if the socket is unbound when this function is called. 


Protocol Basics: Listen, Connect, Accept 


The basic operations involved with establishing a socket connection can be most 
conveniently explained in terms of the client-server paradigm. 


The server side will first create a socket, bind it to a well known local address (so that the 
client can find it), and put the socket in listening mode, through WSPListen, in order to 
prepare for any incoming connection requests and to specify the length of the 

connection backlog queue. Service providers hold pending connection requests in a 
backlog queue until they are acted upon by the server or are withdrawn (due to time-out) 
by the client. A service provider may silently ignore requests to extend the size of the | 
backlog queue beyond a provider-defined upper limit. 


At this point, if a blocking socket is being used, the server side may immediately call 
WSPAccept which will block until a connection request is pending. Conversely, the 
server may also use one of the network event indication mechanisms discussed 
previously to arrange for notification of incoming connection requests. Depending on the 
notification mechanism selected, the provider will either issue a Windows message or 
signal an event object when connection requests arrive. See section Notification of 
Network Events for how to register for the FD_ACCEPT network event. 


The client side will create an appropriate socket, and initiate the connection by calling 
WSPConnect, specifying the known server address. Clients usually do not perform an 
explicit bind operation prior to initiating a connection, allowing the service provider to 
perform an implicit bind on their behalf. If the socket is in blocking mode, WSPConnect 
will block until the server has received and acted upon the connection request (or until a 
time-out occurs). Otherwise, the client should use one of the network event indication 
mechanisms discussed previously to arrange for notification of a new connection being 
established. Depending on the notification mechanism selected, the provider will indicate 
this either through a Windows message or by signaling an event object. 
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When the server side invokes WSPAccept, the service provider calls the application- 
supplied condition function, using function parameters to pass into the server information 
from the top entry in the connection request backlog queue. This information includes 
such things as address of connecting host, any available user data, and any available 
QOS information. Using this information the server’s condition function determines 
whether to accept the request, reject the request, or defer making a decision until later. 
This decision is indicated through the return value of the condition function. See section 
Notification of Network Events for how to register for the FD_CONNECT network event. 


If the server decides to accept the request, the provider must create a new socket with 
all of the same attributes and event registrations as the listening socket. The original 
socket remains in the listening state so that subsequent connection requests can be 
received. Through output parameters of the condition function, the server may also 
supply any response user data and assign QOS parameters (assuming that these 
operations are supported by the service provider). 


Determining Local and Remote Names 


WSPGetSockName is used to retrieve the local address for bound sockets. This is 
especially useful wnen a WSPConnect call has been made without doing a WSPBind 
first; WSPGetSockName provides the only means to determine the local association 
which has been set implicitly by the provider. 


After a connection has been set up, WSPGetPeerName can be used to determine the 
address of the peer to which a socket is connected. 


Enhanced Functionality at Connect Time 


Windows Sockets 2 offers an expanded set of operations that can occur coincident to 
establishing a socket connection. The service provider requirements for implementing 
these features are described below. 


Conditional Acceptance 


As described previously, WSPAccept invokes a client-supplied condition function that 
uses input parameters to supply information about the pending connection request. This 
information can be used by the client to accept or reject a connection request based on 
caller information such as caller identifier, QOS, etc. If the condition function returns 
CF_ACCEPT, a new socket is created with the same properties as the listening socket, 


-and a handle to the new socket is returned. If the condition function returns 


CF_REJECT, the connection request should be rejected. If the condition function returns 
CF_DEFER, the accept/reject decision cannot be made immediately, and the service 
provider must leave the connection request on the backlog queue. The client must call 
WSPAccept again, when it is ready to make a decision, and arrange for the condition 
function to return either CF_ACCEPT or CF_REJECT. While a deferred connection 
request is at the top of the backlog queue, the service provider does not issue any 
further indications for pending connection requests. 
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Exchanging User Data at Connect Time 

Some protocols allow a small amount of user data to be exchanged at connect time. If 
such data has been received from the connecting host, it is placed in a service provider 
buffer, and a pointer to this buffer along with a length value are supplied to the Windows 
Sockets SPI client through input parameters to the WSPAccept condition function. If the 
Windows Sockets SPI client has response data to return to the connecting host, it may 
copy this into a buffer that is supplied by the service provider. A pointer to this buffer and 
an integer indicating buffer size are also supplied as condition function input parameters 
(if supported by the protocol). 


Establishing Socket Groups 
All use of Group Sockets is reserved. 


Connection Shutdown 


The following paragraphs describe operations incident to shutting down an established 
socket connection. 


Initiating Shutdown Sequence 


A socket connection can be taken down in one of several ways. WSPShutdown (with 
how equal to SD_SEND or SD_BOTH), and WSPSendDisconnect may be used to 
initiate a graceful connection shutdown. WSPCloseSocket can be used to initiate either 
a graceful or abortive shutdown, depending on the linger options invoked by the closing 
a socket. See below for more information about graceful and abortive shutdowns, and 
linger options. 


Indicating Remote Shutdown 


Service providers indicate connection teardown that is initiated by the remote party 
through the FD_CLOSE network event. Graceful shutdown is also be indicated through 
WSPRecv when the number of bytes read is 0 for byte-stream protocols, or through a 
return error code of WSAEDISCON for message-oriented protocols. In any case, a 
WSPRecv return error code of WSAECONNRESET indicates an abortive shutdown. 


Exchanging User Data at Shutdown Time 


At connection teardown time, it is also possible (for protocols that support this): to 
exchange user data between the endpoints. The end that initiates the teardown can call 
WSPSendDisconnect to indicate that no more data is to be sent and cause the © 
connection teardown sequence to be initiated. For certain protocols, part of this 
teardown sequence is the delivery of disconnect data from the teardown initiator. After 
receiving notice that the remote end has initiated the teardown sequence (typically _ 
through the FD_CLOSE indication), the WSPRecvDisconnect function may be called to 
receive the disconnect data (if any). 
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To illustrate how disconnect data might be used, consider the following scenario. The 
client half of a client/server application is responsible for terminating a socket 
connection. Coincident with the termination it provides (through disconnect data) the 
total number of transactions it processed with the server. The server in turn responds 
with the cumulative grand total of transactions that it has processed with all clients. The | 
sequence of calls and indications might occur as shown in the following table. 


Client side Server side 


(1) Invokes WSPSendDisconnect to 
conclude session and supply 
transaction total. 


(2) Gets FD_CLOSE, or WSPRecv with a 
return value of zero or WSAEDISCON 
indicating graceful shutdown in progress. 


(3) Invokes WSPRecvDisconnect to get 
client’s transaction total. 


(4) Computes cumulative grand total of all 
transactions. 


(5) Invokes WSPSendDisconnect to transmit 
grand total. 


(6) Receives FD_CLOSE indication. (5a) Invokes WSPClosesocket 


(7) Invokes WSPRecvDisconnect to 
receive and store cumulative grand 
total of transactions. 


(8) Invokes WSPClosesocket 
Step (5a) must follow step (5), but has no timing relationship with-steps (6), (7), or (8). 


Graceful Shutdown, Linger Options, and Socket Closure in the SPI 


It is important to distinguish between shutting down a socket connection and closing a 
socket. Shutting down a socket connection involves an exchange of protocol messages 
between the two endpoints, which is hereafter referred to as a shutdown sequence. Two 
general classes of shutdown sequences are defined: graceful and abortive. In a graceful 
shutdown sequence, any data that has been queued but not yet transmitted can be sent 
prior to the connection being closed. In an abortive shutdown, any unsent data is lost. 
The occurrence of a shutdown sequence (graceful or abortive) can also be used to 
provide an FD_CLOSE indication to the associated applications signifying that a 
shutdown is in progress. Closing a socket, on the other hand, causes the socket handle 


~ to become deallocated so that the application can no longer reference or use the socket 


In any manner. 7 


In Windows Sockets, both the WSPShutdown function, and the WSPSendDisconnect 
function can be used to initiate a shutdown sequence, while the WSPCloseSocket 
function is used to deallocate socket handles and free up any associated resources. 


Chapter 10 Winsock 2 SPI Overview 447 


Some amount of confusion arises, however, from the fact that the WSPCloseSocket 
function will implicitly cause a shutdown sequence to occur if it has not already 
happened. In fact, it has become a rather common programming practice to rely on this 
feature and use WSPCloseSocket to both initiate the shutdown sequence and 
deallocate the socket handle. 


To facilitate this usage, the sockets interface provides for controls through the socket 
option mechanism that allows the programmer to indicate whether the implicit shutdown 
sequence should be graceful or abortive, and also whether the WSPCloseSocket 
function should linger that is, not complete immediately) to allow time fora graceful 
shutdown sequence to complete. 


By establishing appropriate values for the socket options SO_LINGER and 
SO_DONTLINGER,, the following types of behavior can be obtained with the 
WSPCloseSocket function. 


e Abortive shutdown sequence, immediate return from WSPCloseSocket. 


e Graceful shutdown, delay return until either shutdown sequence completes or a 
specified time interval elapses. If the time interval expires before the graceful 
shutdown sequence completes, an abortive shutdown sequence occurs and 

~ WSPCloseSocket returns. 


e Graceful shutdown, return immediately, and allow the shutdown sequence to 
complete in the background. This is the default behavior. Note, however, that the 
application has no way of knowing when (or whether) the gracetul shutdown 
sequence completes. 


One technique that can be used to minimize the chance of problems occurring during 
connection teardown is not to rely on an implicit shutdown being initiated by 
WSPCloseSocket. Instead, one of the two explicit shutdown functions (WSPShutdown 
or WSPSendDisconnect ) are used. This in turn will cause an FD_CLOSE indication to 
be received by the peer application indicating that all pending data has been received. 
To illustrate this, the following table shows the functions that would be invoked by the 
client and server components of an application, where the client is responsible for 
initiating a graceful shutdown. 


Client side | Server side | 


(1) Invokes WSPShutdown (s, 
SD_SEND) to signal end of session and 
that client has no more data to send. 
i | | (2) Receives FD_CLOSE, indicating graceful 
_ shutdown in progress and that all data has 
_ been received. 
(3) Sends any remaining response data. 


(continued) 
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(continued) 


Client side | Server side 


(5a) Gets FD_READ and invoke recvto (4) Invokes WSPShutdown(s, SD_SEND) to 
get any response data sent by server. indicate server has no more data to send. 


(5) Receives FD_CLOSE indication. (4a) Invokes WSPCloseSocket | 
(6) Invokes WSPCloseSocket 


_ The timing sequence is maintained from step (1) to step (6) between the client and the 


server, except for steps (4a) and (5a) which only have local timing significance in the 
sense that step (5) follows step (5a) on the client side while step (4a) follows step (4) on 
the server side, with no timing relationship with the remote party. 


Socket Connections on Connectionless Protocols 


The following sections describe the semantics of using connect operations on 
connectionless protocols such as UDP and IPX. 


Connecting to a Default Peer 


For a socket bound to a connectionless protocol, the operation performed by 
WSPConnect is merely to establish a default destination address so that the socket may 
be used with subsequent connection-oriented send and receive operations (WSPSend 
and WSPRecv). Any datagrams received from an address other than the destination 
address specified will be discarded. 


Reconnecting and Disconnecting 

The default destination may be changed by simply calling WSPConnect again, even if 
the socket is already connected. Any datagrams queued for receipt are discarded if the 
new address is different from the address specified in a previous WSPConnect. 


lf the address supplied is all zeroes, the socket will be disconnected—the default remote 
address will be indeterminate, so WSPSend and WSPRecv calls will return the error 
code WSAENOTCONN, although WSPSendTo and WSPRecvFrom may still be used. 


Using Sendto While Connected 


WSPSendTo will always deliver the data to the specified address, even though a 
designated peer for the sending socket has been established i in WSPConnect. 


Socket I/O 


There are three primary ways of doing I/O in Windows Sockets 2: 


e Blocking I/O. 
e Nonblocking |/O along with asynchronous notification of network events. 
e Overlapped I/O with completion indication. 
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We describe each method in the following sections. Blocking I/O is the default behavior, 
nonblocking mode can be used on any socket that is placed into nonblocking mode, and 
overlapped I/O can only occur on sockets that are created with the overlapped attribute. 
It is also interesting to note that the two calls for sending: WSPSend and WSPSendTo 

_ and the two calls for receiving: WSPRecv and WSPRecvFrom each implement all three 
methods of I/O. Service providers determine how to perform the I/O operation based on 

socket modes and attributes and the input parameter values. 


Blocking Input/Output 


The simplest form of I/O in Windows Sockets 2 is blocking I/O. As mentioned in section 
Socket Attribute Flags and Modes, sockets are created in blocking mode by default. Any 
I/O operation with a blocking socket will not return until the operation has been fully 
completed. Thus, any thread can only execute one I/O operation at a time. For example, 
if a thread issues a receive operation and no data is currently available, the thread will 
block until data becomes available and is placed into the thread’s buffer. Although this is 
simple, it is not necessarily the most efficient way to do I/O in all versions of Windows. In 
Win16 environments for example, blocking is strongly discouraged due to the 
nonpreemptive nature of the operating system. (see section Pseudo vs. True Blocking 
for more information). 


Nonblocking Input/Output 


If a socket is in a nonblocking mode, any I/O operation must either complete immediately 
or return error code WSAEWOULDBLOCK indicating that the operation cannot be 
finished right away. In the latter case, a mechanism is needed to discover when it is 
appropriate to try the operation again with the expectation that the operation will 
succeed. A set of network events has been defined for this purpose. These events can 
be polled or waited on by using WSPSelect, or they can be registered for asynchronous 
delivery by calling WSPAsyncSelect or WSPEventSelect. (see section Notification of 
Network Evenis for more information) 


Overlapped Input/Output 


Windows Sockets 2 introduces overlapped I/O and requires that all transport providers 
support this capability. Overlapped I/O can be performed only on sockets that were 
created through the WSPSocket function with the WSA_FLAG_OVERLAPPED flag set, 
and follow the model established in Win32. 


For receiving, a client uses WSPRecv or WSPRecvFrom to supply buffers into which 
data is to be received. If one or more buffers are posted prior to the time when data has 
been received by the network, it is possible that data will be placed into the user’s 
buffers immediately as it arrives and thereby avoid the copy operation that would 
otherwise occur. If data is already present when receive buffers are posted, it is copied 
immediately into the user’s buffers. If data arrives when no receive buffers have been 


~ posted by the application, the service provider resorts to the synchronous style of 


operation where the incoming data is buffered internally until such time as the client 
_ issues a receive call and thereby supplies a buffer into which the data may be copied. 
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An exception to this would be if the application used WSPSetSockOpt to set the size of | 
the receive buffer to zero. In this instance, reliable protocols would only allow data to be 
received when application buffers had been posted, and data on unreliable protocols 
would be lost. , | 


On the sending side, clients use WSPSend or WSPSendTo to supply pointers to filled 
buffers and then agree not to disturb the buffers in any way until the network has 
consumed the buffer’s contents. 


Overlapped send and receive calls return immediately. A return value of zero indicates 
that the I/O operation completed immediately and that the corresponding completion 
indication has already occurred. That is, the associated event object has been signaled, 
or the completion routine has been queued through WPUQueueApc. A return value of 
SOCKET_ERROR coupled with an error code of WSA_IO_PENDING indicates that the 
overlapped operation has been successfully initiated and that a subsequent indication 
will be provided when send buffers have been consumed or when receive buffers are 
filled. Any other error code indicates that the overlapped operation was not successfully 
initiated and that no completion indication will be forthcoming. 


Both send and receive operations can be overlapped. The receive functions may be 
invoked multiple times to post receive buffers in preparation for incoming data, and the 
send functions may be invoked multiple times to queue up multiple buffers to be sent. 
Note that while a series of overlapped send buffers will be sent in the order supplied, the 
corresponding completion indications may occur in a different order. Likewise, on the 
receiving side, buffers will be filled in the order they are supplied, but completion 
indications may occur in a different order. 


The deferred completion feature of overlapped I/O is also available for WSPloctl. 


Delivering Completion Indications 


Service providers have two ways to indicate overlapped completion: setting a client- 
specified event object, or invoking a client-specified completion routine. In both cases a 
data structure, WSAOVERLAPPED, is associated with each overlapped operation. This 
structure is allocated by the client and used by it to indicate which event object (if any) is 
to be set when completion occurs. The WSAOVERLAPPED structure may be used by 
the service provider as a place to store a handle to the results (for example, number of 
bytes transferred, updated flags, error codes, etc.) for a particular overlapped operation. 
To obtain these results clients must invoke WSPGetOverlappedResult, passing in a 
pointer to the corresponding overlapped structure. 


lf event based completion indication is selected for a particular overlapped I/O request, 
the WSPGetOverlappedResult routine may itself be used by clients to either poll or wait 
for completion of the overlapped operation. If completion-routine-based completion 
indication is selected for a particular overlapped I/O request, only the polling option of 
WSPGetOverlappedResult is available. A client may also use other means to wait 


_ (such as using WSAWaitForMultipleEvents) until the corresponding event object has 
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been signaled or the specified completion routine has been invoked by the service 
provider. Once completion has been indicated, the client may invoke 
WSPGetOverlappedResult, with the expectation that the call will complete immediately. 


Invoking Socket I/O Completion Routines 


If the /oCompletionRoutine parameter to an overlapped operation is not NULL, it is the 
service provider’s responsibility to arrange for invocation of the client-specified 
completion routine when the overlapped operation completes. Since the completion 
routine must be executed in the context of the same thread that initiated the overlapped 
operation, it cannot be invoked directly from the service provider. The Ws2_32.dll offers 
an asynchronous procedure call aa mechanism to facilitate invocation of completion 
routines. 3 


A service provider arranges for a function to be executed in the proper thread by calling 
WPUQueueApc. This function can be called from any process and thread context, even 
a context different from the thread and process that was used to initiate the overlapped 
operation. 


WPUQueueApc takes as input parameters a siniel to a WSATHREADIDID structure, a 
pointer to an APC function to be invoked, and a 32-bit context value that is subsequently 
passed to the APC function. Service providers are always supplied with a pointer to the 
proper WSATHREADDD structure through the /pThreadid parameter to the overlapped 
function. The provider should store the WSATHREADID structure locally and supply a 
pointer to this copy of the WSATHREADID structure as an input parameter to 
WPUQueueApc. Once the WPUQueueApc function returns, the provider can dispose of 
its copy of the WSATHREADID. , 


The procedure WPUQueueApc simply enqueues sufficient information to call the 
indicated APC function with the given parameters, but does not call it. When.the target 
thread enters an alertable wait state, this information is dequeued and a call is made to 

_ the APC function in that target thread and process context. Because the APC 
mechanism supports only a single 32-bit context value, the APC function cannot itself be 
the client-specified completion routine, which involves more parameters. The service 
provider must instead supply a pointer to its own APC function which uses the supplied 
context value to access the needed result information for the overlapped operation, and 
then invokes the client-specified completion routine. 


For service providers where a user-mode component implements overlapped /O, a 
typical usage of the APC mechanism is as follows: 1 


¢ When the I/O operation completes, the provider allocates a small buffer and packs it 
with a pointer to the client-supplied completion procedure and parameter ¥ values to 
pass to the procedure. © 


e |t queues an APC, specifying the pointer to the buffer as the context value and its own 
intermediate procedure as the target procedure. 


e When the target thread eventually enters alertable wait state, the service provider's 
___ intermediate procedure is called in the proper thread context. 
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e The intermediate procedure simply unpacks parameters, deallocates the buffer, and 
calls the client-supplied completion procedure. 


e For service providers where a kernel-mode component implements wielaeeed /O, a 
typical implementation is similar, except that the Implementation would use standard 
kernel interfaces to enqueue the APC. 


Description of the relevant kernel interfaces is outside the scope of the Windows 
Sockets 2 specification. 


Important Service providers must allow Windows Sockets 2 clients to invoke send and 
receive operations from within the context of the socket I/O completion routine, and 
guarantee that, for a given socket, I/O completion routines will not be nested. 


Under some circumstances, a layered service provider may need to initiate and 
complete overlapped operations from within an internal worker thread. In this case, a 
WSATHREADID would not be available from an incoming function call. The service 
provider interface provides an upcall, WPUOpenCurrentThread, to obtain a 
WSATHREADID for the current thread. When this WSATHREADID is no longer needed, 
its resources should be returned by calling WPUCloseThread. 


Summary of Overlapped Completion Indication Mechanisms in the SPI 


The following table summarizes the completion semantics for an overlapped socket, 
showing the various combination of JoOverlapped, hEvent, and lpCompletionRoutine: 


IpOverlapped hEvent IpCompletionRoutine Completion indication 


NULL Not applicable Ignored Operation completes 
synchronously, that is, it 
behaves as if it were a 
nonoverlapped socket. 


INULL NULL NULL Operation completes 
overlapped, but there is no 
Windows Sockets 2- 
supported completion 
mechanism. The completion 
port mechanism 
(if supported) may be used 
in this case, otherwise there 
will be no completion 

~ notification. 
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IpOverlapped hEvent IpCompletionRoutine Completion indication 


INULL INULL NULL Operation completes 
overlapped, notification by 
signaling event object. 

INULL Ignored NULL Operation completes 

: overlapped, notification by 
scheduling completion 
routine. 


Support for Scatter/Gather Input/Output in the SPI 


The WSPSend, WSPSendTo, WSPRecv, and WSPRecvFrom routines all take an 
array of client buffers as input parameters and thus may be used for scatter/gather 

(or vectored) I/O. This can be very useful in instances where portions of each message 
being transmitted consist of one or more fixed length header components in addition to a 
message body. Such header components need not be concatenated into a single 
contiguous buffer prior to sending. Likewise on receiving, the header components can be 
automatically split off into separate buffers, leaving the message body pure. 


Utilizing lists of buffers instead of a single buffer does not change the boundaries that 
apply to receive operations. For message-oriented protocols, a receive operation 
completes whenever a single message has been received, regardless of how many or 
few of the supplied buffers were used. Likewise for stream-oriented protocols, a receive 
completes when an unspecified quantity of bytes arrives over the network, not 
necessarily when all of the supplied buffers are full. 


Out-of-Band Data in the SPI 


The service providers which support the out-of-band data (OOB) abstraction for the 
stream-style sockets must adhere to the semantics in this section. We will describe OOB 
data handling in a protocol-independent manner. Please refer to the Windows Sockets 2 
_Protocol-Specific Annex (a separate document) for a discussion of OOB data 

~ implemented using urgent data in TCP/IP service providers. In the following, the use of 
WSPRecv also implies WSPRecvFrom. 


Protocol Independent-Out-of-Band Data in the SPI 


OOB data is a logically independent transmission channel associated with each pair of 
connected stream sockets. OOB data may be delivered to the user independently of 
normal data. The abstraction defines that the OOB data facilities must support the 
reliable delivery of at least one OOB data block at a time. This data block may contain at 
least one byte of data, and at least one OOB data block may be pending delivery to the 
user at any one time. For communications protocols which support in-band signaling 
(that is, TCP, where the urgent data is delivered in sequence with the normal data), the 
system normally extracts the OOB data from the normal data stream and stores it 
separately (leaving a gap in the normal data stream). This allows users to choose 
between receiving the OOB data in order and receiving it out of sequence without having 
to buffer all the intervening data. It is possible to peek at OOB data. | 
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A user can determine if there is any OOB data waiting to be read using the 
WSPloctl(SIOCATMARK) function. For protocols where the concept of the position of 
the OOB data block within the normal data stream is meaningful (that is, TCP), a 
Windows Sockets service provider will maintain a conceptual marker indicating the 
position of the last byte of OOB data within the normal data stream. This is not 
necessary for the implementation of the WSPloctl (SIOCATMARK) functionality—the 
presence or absence of OOB data is all that is required. 


For protocols where the concept of the position of the OOB data block within the normal 
data stream is meaningful an application may prefer to process out-of-band data inline, 
as part of the normal data stream. This is achieved by setting the socket option 
SO_OOBINLINE (see section WSPloctl). For other protocols where the OOB data 


— blocks are truly independent of the normal data stream, attempting to set 


SO_OOBINLINE will result in an error. An application can use the SSOCATMARK 
WSPloctl command to determine whether there is any unread OOB data preceding the 


_ mark. For example, it might use this to resynchronize with its peer by ensuring that all 


data up to the mark in the data stream is discarded when appropriate. 
With SO_OOBINLINE disabled (by default): 


e The Windows Sockets service provider notifies a client of an FD_OOB event, if the 
client registered for notification with WSPAsyncSelect, in exactly the same way 
FD_READ is used to notify of the presence of normal data. That is, FD_OOB is 
posted when OOB data arrives and there was no OOB data previously queued, and 
also when data is read using the MSG_OOB flag, and some OOB data remains to be 
read after the read operation has returned. FD_READ messages are not posted for 
OOB data. 


e The Windows Sockets service provider returns from WSPSelect with the appropriate 
— exceptfds socket set if OOB data is queued on the socket. 


e The client can call WSPRecv with MSG_OOB to read the urgent data block at any 
time. The block of OOB data jumps the queue. 


e The client can call WSPRecv without MSG_OOB to read the normal data stream. The 
OOB data block will not appear in the data stream with normal data. If OOB data 
remains after any call to WSPRecv, the service provider notifies the client with 
FD_OOB or through exceptfds when using WSPSelect. — 


e For protocols where the OOB data has a position within the normal data stream, a 
single WSPRecv operation will not span that position. One WSPRecv will return the 
normal data before the mark, and a second WSPRecv is required to begin reading 

data after the mark. | i 


With SO_OOBINLINE enabled: 


e FD_OOB messages are not posted for OOB data—for the purpose of the WSPSelect 
and WSPAsyncSelect functions, OOB data is treated as normal data, and indicated 
by setting the socket in readfds or by sending an FD_READ message respectively. 
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e The client may not call WSPRecv with the MSG_OOB flag set to read the OOB data 
block—the error code WSAEINVAL will be returned. 


e The client can call WSPRecv without the MSG_OOB flag set. Any OOB data will be 
delivered in its correct order within the normal data stream. OOB data will never be 
mixed with normal data—there must be three read requests to get past the OOB data. 
The first returns the normal data prior to the OOB data block, the second returns the 
OOB data, the third returns the normal data following the OOB data. In other words, 
the OOB data block boundaries are preserved. 


The WSPAsyncSelect routine is particularly well suited to handling notification of the 
presence of OOB data when SO_OOBINLINE is off. 


Shared Sockets in the SPI 


Socket sharing between processes in Windows Sockets is implemented as follows. A 
source process calls WSPDuplicateSocket to obtain a special 
WSAPROTOCOL_INFOW structure. It uses some interprocess communications (IPC) 
mechanism to pass the contents of this structure to a target process. The target process 
then uses the WSAPROTOCOL_INFOW structure in a call to WSPSocket. The socket 
descriptor returned by this function will be an additional socket descriptor to an 
underlying socket which thus becomes shared. 


It is the service provider's responsibility to perform whatever operations are needed in 
the source process context and to create a WSAPROTOCOL_INFOW structure that will 
be recognized when it subsequently appears as a parameter to WSPSocket in the 
target processes’ context. The dwProviderReserved parameter of the | 
~WSAPROTOCOL_INFOW structure is available for the service provider’s use, and may 
be used to store any useful context information, including a duplicated handle. 


This mechanism is designed to be appropriate for both single-threaded versions of 
Windows (such as Windows 3.1) and preemptive multithreaded versions of Windows 
(such as Windows 95 and Windows NT/Windows 2000). Note however, that sockets | 
may be shared amongst threads in a given process without using the 
WSPDuplicateSocket function, since a socket descriptor | is valid t in all of a process’ 
threads. 


As is described In action Descriptor Allocation, when new socket deeciipiors are 
allocated IFS providers must call WEUModitylFSHandle and nonlFS providers must call 
WPUCreateSocketHandle. | 


One possible scenario for aaa: and using a shared socket | in a handoff mode Is 
illustrated here. | 
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Source process ? IPC - Destination process 
1) WSPSocket, WSPConnect - 

2) Requests target process = 

identifier. 


3) Receives process identifier request 
and responds. 


4) Receives process identifier. a 


5) Calls WSPDuplicateSocket to 
get a special 
WSAPROTOCOL_INFOW 
structure. 


6) Sends 
WSAPROTOCOL_INFOW 
structure to target. 


=> 7) Receives WSAPROTOCOL_INFOW 
structure. 


8) Calls WSPSocket to create shared 
socket descriptor. 


10) WSPClosesocket 9)Uses shared socket for data 
exchange. 


Multiple Handles to a Single Socket 


Since what are duplicated are the socket descriptors and not the underlying sockets, all 
of the states associated with a socket are held in common across all the descriptors. For 
example a WSPSetSockOpt operation performed using one descriptor is subsequently 
visible using a WSPGetSockOpt from any or all descriptors. 


Notification on shared sockets is subject to the usual constraints of WSPAsyncSelect 
and WSPEventSelect. Issuing either of these calls using any of the shared descriptors 
cancels any previous event registration for the socket, regardless of which descriptor 
was used to make that registration. Thus, for example, it would not be possible to have 
process A receive FD_READ events and process B receive FD_WRITE events. For 
situations when such tight coordination is required, it is cecamaats that developers 
consider using threads instead of separate processes. 


Reference Counting 

A process may call WSPCloseSocket on a duplicated socket and the descriptor will 
become deallocated. The underlying socket, however, will remain open until | 
WSPCloseSocket is called on the last remaining descriptor. 
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Precedence Guidelines 


The two (or more) descriptors that reference a shared socket may be used 
independently as far as I/O is concerned. However, the Windows Sockets interface does 
not implement any type of access control, so it is up to the processes involved to 
coordinate their operations on a shared socket. A typical use for shared sockets is to 
have one process that is responsible for creating sockets and establishing connections 
hand off sockets to other processes which are responsible for information exchange. 


The general guideline for supporting multiple outstanding operations on shared sockets 
is that a service provider is encouraged to honor all simultaneous operations on shared 
sockets, especially the most recent operation on a socket object. If need be, this may 
occur at the expense of aborting some of the previous but still pending operations, which 
will return WSAEINTR in this case. 


Protocol-Independent Multicast and Multipoint in the SPI 


Just as Windows Sockets 2 allows the basic data transport capabilities of numerous 
transport protocols to be accessed in a generic manner, it also provides a generic way to 
use multipoint and multicast capabilities of transports that implement these features. To 
simplify, the term multipoint is used hereafter to refer to both multicast and multipoint 
communications. 


Current multipoint implementations (for example, IP multicast, ST-II, T.120, ATM UNI, 
etc.) vary widely with respect to how nodes join a multipoint session, whether a particular 
node is designated as a central or root node, and whether data is exchanged between 

all nodes or only between a root node and the various leaf nodes. The Windows Sockets 
2 WSAPROTOCOL_INFOW structure is used to declare the various multipoint attributes 
of a protocol. By examining these attributes the programmer will know what conventions 
to follow in using the applicable Windows Sockets 2 functions to set up, use, and tear 
down multipoint sessions. 


The features of Windows Sockets 2 that support multicast can be summarized as 
follows: 

e Three attribute bits in the WSAPROTOCOL.INFOW structure. 

e Four flags defined for the dwFlags parameter of WSPSocket 

¢ One function, WSPJoinLeaf, for adding leaf nodes into a multipoint session. 


¢ Two WSPloctl command codes for controlling multipoint loopback and establishing 
_ the scope for multicast transmissions. (The latter corresponds to the IP multicast 
time-to-live or TTL parameter.) Pe 


Note The inclusion of these multipoint features in Windows Sockets 2 does not 
_ preclude a service provider from also supporting an existing protocol-dependent 
interface, such as the Deering socket options for IP multicast. 
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Multipoint Taxonomy and Glossary 


The taxonomy described below first distinguishes the control plane that concerns itself 
with the way a multipoint session is established, from the data plane that deals with the 


transfer of data among session participants. 


In the control plane, there are two distinct types of session establishment: rooted and 
nonrooted. In the case of rooted control, there exists a special participant, called c_root, 
that is different from the rest of the members of this multipoint session, each of which is 
called a c_leaf. The c_root must remain present for the whole duration of the multipoint 
session, as the session will be broken up in the absence of the c_root. The c_root 
usually initiates the multipoint session by setting up the connection to a c_leaf, or a 
number of c_leafs. The c_root may add more c_leafs, or (in some cases) a c_leaf can 
join the c_root at a later time. Examples of the rooted control plane can be found in ATM 
and ST-ll. 


For a nonrooted control plane, all members belonging to a multipoint session are leaves, 
that is, no special participant acting as a c_root exists. Each c_leaf needs to add itself to 
a pre-existing multipoint session that either is always available (as in the case of an IP 
multicast address), or has been set up through some OOB mechanism which is outside 
the scope of this discussion (and hence not addressed in the proposed Windows 
Sockets extensions). Another way to look at this is that a c_root still exists, but can be 
considered to be in the network cloud as opposed to one of the participants. Because a 
control root still exists, a nonrooted control plane could also be considered to be 
implicitly rooted. Examples of this kind of implicitly rooted multipoint schemes are: a 
teleconferencing bridge, the IP multicast system, a Multipoint Control Unit (MCU) in an 
H.320 video conference, etc. 


In the data plane, there are also two types of data transfer styles: rooted and nonrooted. 
In a rooted data plane, a special participant called d_root exists. Data transfer only 
occurs between the d_root and the rest of the members of this multipoint session, each 
of which is referred to as a d_leaf. The traffic could be unidirectional, or bidirectional. The 
data sent out from the d_root will be duplicated (if required) and delivered to every 
d_leaf, while the data from d_leafs will only go to the d_root. In the case of a rooted data 
plane, there is no traffic allowed among d_leafs. An example of a protocol that is rooted 
in the data plane is ST-II. 


In a nonrooted data plane, all the participants are equal in the sense that any data they 
send will be delivered to all the other participants in the same multipoint session. 
Likewise each d_leaf node will be able to receive data from all other d_leafs, and in 
some cases, from other nodes which are not participating in the multipoint session as 
well. No special d_root node exists. |P-multicast is nonrooted in the data plane. 


Note that the question of where data unit duplication occurs, or whether a shared single 
tree or multiple shortest-path trees are used for multipoint distribution are protocol 
issues., AS such, they are irrelevant to the interface the client would use to perform 
multipoint communications. Therefore these | issues are not addressed by the Windows 
Sockets interface. 
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The following table depicts the taxonomy described above and indicates how existing 
schemes fit into each of the categories. Note that there does not appear to be any 
multipoint schemes that employ a nonrooted control plane along with a rooted data 
plane. 


Rooted control Nonrooted (implicit rooted) 

plane control plane | 
Rooted data plane ATM, ST-II No known examples 
Nonrooted data plane T.120 IP-multicast, H.320 (MCU) 


Multipoint Attributes in the WSAPROTOCOL_INFOW Structure 


Three attribute parameters are defined in the WSAPROTOCOL_INFOW structure in 
order to distinguish the different schemes used in the control and data planes, 
respectively: 


e XP1_SUPPORT_MULTIPOINT with a value of 1 indicates this protocol entry supports 
_ multipoint communications, and that the following two parameters are meaningful. 
e XP1_MULTIPOINT_CONTROL_PLANE indicates whether the control plane is rooted 
(value = 1) or nonrooted (value = 0). 


e XP1_MULTIPOINT_DATA_PLANE indicates whether the data plane is rooted 
(value = 1) or nonrooted (value = 0). 


Two WSAPROTOCOL_INFOW entries would be present if a multipoint protocol 
supported both rooted and nonrooted data planes, one entry for each. 


Multipoint Socket Attributes 


In some instances sockets joined to a multipoint session may have some behavioral 
differences from point-to-point sockets. For example, a d_leaf socket in a rooted data 

_ plane scheme can only send information to the d_root participant. This creates a need 
for the client to be able to indicate the intended use of a socket coincident with its 
creation. This is done through four multipoint attribute flags that can be set through the 
dwFlags parameter in WSPSocket: : | 


e WSA_FLAG_MULTIPOINT_C_ROOT, for the creation of a socket acting as a c_root, 
and only allowed if a rooted control plane is indicated in the aoa 

~ WSAPROTOCOL_INFOW entry. 

e WSA_FLAG_MULTIPOINT_C_LEAF, for the creation of a soeket aclitie as a C_leaf, 
and only allowed if XP 1 SUPPORT: MULTIPOINT 1 is indicated in the corresponding 
WSAPROTOCOL_INFOW entry. | 

e WSA_ FLAG_MULTIPOINT_D_ROOT, for the creation of a socket acting as a d_root, 
and only allowed if a rooted data plane is indicated in the Corresponding 
WSAPROTOCOL_ INFOW enty. ee 
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e WSA_FLAG_MULTIPOINT_D_LEAF, for the creation of a socket acting as a d_leaf, 
and only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the corresponding 
WSAPROTOCOL_INFOW entry. 


When creating a multipoint socket, exactly one of the two control plane flags, and one of 
the two data plane flags must be set in WSPSocket’s dwFlags parameter. Thus, the four 
possibilities for creating multipoint sockets are: “c_root/d_root”, “c_root/d_leaf”, 
“c_leaf/d_root’, or “c_leaf /d_leaf”. 


SIO_MULTIPOINT_LOOPBACK loctl 


When d_leaf sockets are used in a nonrooted data plane, it is generally desirable to be 


_able to control whether traffic sent out is also received back on the same socket. The 


SIO_MULTIPOINT_LOOPBACK command code for WSPloctl is used to enable or 
disable loopback of multipoint traffic. 


SIO MULTICAST SCOPE loctl 


When multicasting is employed, it is usually necessary to specify the scope over which 
the multicast should occur. Here scope is defined to be the number of routed network 
segments to be covered. The SIO_MULTICAST_SCOPE command code for WSPloctl 


_ is used to control this. A scope of zero would indicate that the multicast transmission 


would not be placed on the wire but could be disseminated across sockets within the 
local host. A scope value of one (the default) indicates that the transmission will be 
placed on the wire, but will not cross any routers. Higher scope values determine the 
number of routers that may be crossed. Note that this corresponds to the time-to-live 
(TTL) parameter in IP multicasting. 


SPI Semantics for Joining Multipoint Leaves 


In the following, a multipoint socket is frequently characterized by describing its role in 
one of the two planes (control or data). It should be understood that this same socket 
has a role in the other plane, but this is not mentioned in order to keep the references 
short. For example a reference to a c_root socket could refer to elliot a c_root/d_root or 
a c_root/d_leaf socket. 


In rooted control plane schemes, new leaf nodes are added to a multipoint session in 
one or both of two different ways. In the first method, the root uses WSPJoinLeaf to 
initiate a connection with a leaf node and invite it to become a participant. On the leaf 
node, the peer application must have created a c_leaf socket and used WSPListen to 
set it into listen mode. The leaf node will receive an FD_ACCEPT indication when invited 
to join the session, and signals its willingness to join by calling WSPAccept. The root 
application will receive an FD_CONNECT indication when the join operation has been 
completed. | | 


In the second method, the roles are essentially reversed. The root client creates a c_root 
socket and sets it into listen mode. A leaf node wishing to join the session creates a 
c_leaf socket and uses WSPJoinLeaf to initiate the connection and request admittance. 
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The root client receives FD_ACCEPT when an incoming admittance request arrives, and 
admits the leaf node by calling WSPAccept. The leaf node receives FD_CONNECT 
when it has been admitted. 


In a nonrooted control plane, where all nodes are c_leafs, the WSPJoinLeaf function is 
used to initiate the inclusion of a node into an existing multipoint session. An 
FD_CONNECT indication is provided when the join has been completed and the 
returned socket descriptor is useable in the multipoint session. In the case of IP 
multicast, this would correspond to the IP_LADD_MEMBERSHIP socket option. 


There are, therefore, three instances where a client would use WSPJoinLeaf: 


e Acting as a multipoint root and inviting a new leaf to join the session. 
© Acting as a leaf making an admittance request to a rooted multipoint session. 


e Acting as a leaf seeking admittance to a nonrooted multipoint session (for example, 
IP multicast.) | 


Using WSPJoinLeaf 


As mentioned previously, WSPJoinLeaf is used to join a leaf node into a multipoint 
session. WSPJoinLeaf has the same parameters and semantics as WSPConnect 
except that it returns a socket descriptor (as in WSPAccept), and it has an additional 
dwFlags parameter. The dwFlags parameter is used to indicate whether the socket will 
be acting only as a sender, only as a receiver, or both. Only multipoint sockets may be 
used for input parameter s in this function. If the multipoint socket is in the nonblocking 
mode, the returned socket descriptor will not be useable until after a corresponding 
FD_CONNECT indication has been received. A root application in a multipoint session 
may call WSPJoinLeaf one or more times in order to add a number of leaf nodes, 
however at most one multipoint connection request may be outstanding at a time. 


The socket descriptor returned by WSPJoinLeaf is different depending on whether the 
input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the 
name parameter designates a particular leaf node to be added and the returned socket 
descriptor is a c_leaf socket corresponding to the newly added leaf node. It is not 
intended to be used for exchange of multipoint data, but rather is used to receive 
network event indications (for example FD_CLOSE) for the connection that exists to the 
particular c_leaf. Some multipoint implementations may also allow this socket to be used 
for side chats between the root and an individual leaf node. An FD_CLOSE indication 
should be given for this socket if the corresponding leaf node calls WSPCloseSocket to 
drop out of the multipoint session. Symmetrically, invoking WSPCloseSocket on the | 
c_leaf socket returned from WSPJoinLeaf will cause the socket i in the corresponding 
leaf node to get FD_CLOSE notification. , 


When WSPVoinLeaf is invoked with a c_leaf socket, the name parameter contains the 
__ address of the root application (for a rooted control scheme) or an existing multipoint 
session (nonrooted control scheme), and the returned socket descriptor is the same as 
the input socket descriptor. In a rooted control scheme, the root client would put its 
c_root socket in the listening mode by calling WSPListen. The standard FD_ACCEPT 
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notification will be delivered when the leaf node requests to join itself to the multipoint 
session. The root client uses the usual WSPAccept function to admit the new leaf node. 
The value returned from WSPAccept is also a c_leaf socket descriptor just like those — 
returned from WSPuJoinLeaf. To accommodate multipoint schemes that allow both root- 
initiated and leaf-initiated joins, it is acceptable for a c_root socket that is already in 
listening mode to be used as in input to WSPJoinLeaf. 


A multipoint root client is generally responsible for the orderly dismantling of a multipoint 
session. Such an application may use WSPShutdown or WSPClosesocket on a c_root 
socket to cause all of the associated c_leaf sockets, including those returned from 
WSPJoinLeaf and their corresponding c_leaf sockets in the remote leaf nodes, to get 
FD_CLOSE notification. 


Semantic Differences Between Multipoint Sockets and Regular 
Sockets in the SPI 


In the control plane, there are some significant semantic differences between a c_root 
socket and a regular point-to-point socket: 7 


e The c_root socket can be used in WSPJoinLeaf to join a new leaf. 


e Placing a c_root socket into the listening mode (by calling WSPListen) does not 
preclude the c_root socket from being used in a call to WSPJoinLeaf to add a new 
leaf, or for sending and receiving multipoint data. 


e The closing of a c_root socket will cause all the associated c_leaf sockets to get 
FD_CLOSE notification. 


There are no semantic differences between a c_leaf socket and a regular socket in the 
control plane, except that the c_leaf socket can be used in WSPUJoinLeaf, and the use 
of c_leaf socket in WSPListen indicates that only multipoint connection requests should 
be accepted. 


In the data plane, the semantic differences between the d_root socket and a regular 
point-to-point socket are 


e The data sent on the d_root socket will be delivered to all the leaves in the same 
multipoint session. 


e The data received on the d_root socket may be from any of the leaves. 


: The d_leaf socket in the rooted data plane has no semantic difference from the regular 


socket, however, in the nonrooted data plane, the data sent on the d_leaf socket will go 
to all the other leaf nodes, and the data received could be from any other leaf nodes. As 
mentioned earlier, the information about whether the d_leaf socket is in a rooted or 


-nonrooted data plane is contained in the eoy > eneing WSAPROTOCOL_INFOW 


uate for the socket. 


socket Options and lIOCTLs 
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The socket options for Windows Sockets 2 are summarized in the following table. More | 
detailed information is provided in section 4 under WSPGetSockOpt and/or 
WSPSetSockOpt. There are other new protocol-specific socket eptens which can be 
found in the Protocol-Specific Annex. 


A Windows Sockets service provider must recognize all of these options, and (for 
WSPGetSockOpt) return plausible values for each. The default value for each option is 
shown in the following table. 


Value 


SO_ACCEPTCONN 


SO_BROADCAST 


SO_DEBUG | 
SO_DONTLINGER 


SO_DONTROUTE | 


SO_ERROR 
SO_GROUP_ID 
-$O_GROUP_ 


PRIORITY 
-SO_KEEPALIVE 


SO_ LINGER 


Type 
BOOL 


BOOL 


BOOL 


BOOL 


BOOL 


int 


GROUP 


int. 


BOOL 


Structure linger 


Meaning 


Socket is listening. 


Socket is configured. 


for the transmission of 
broadcast messages. 


Debugging is enabled. 
lf true, the | 


SO_LINGER option is 


disabled. 


Routing is disabled. 
~ Not supported on ATM 


sockets (results in an 
error). 


Retrieves error status 


and clear. 


_ Reserved. 
Reserved. 


 Keepalives are being 
__ sent. Not supported on 


ATM sockets (results 


_ in an error). 
Returns the current 
_ linger options. 


Default 


FALSE unless 
a WSPListen 
has been 
performed. 


“FALSE 


FALSE 


TRUE | 


FALSE 


NULL 
_ FALSE 


L_onoff is 0 ‘i 


Note 


" 


0 


Get 
only 


( 
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(continued) 


Value 


SO_MAX_MSG__ 
SIZE 


SO_OOBINLINE 


SO_PROTOCOL_ 
INFOW 


SO_RCVBUF 


- S§O_REUSEADDR 


SO_SNDBUF 


SO_TYPE 


PVD_CONFIG 


TCP_NODELAY 


Type 


int 


BOOL 


structure 


WSAPROTOCOL_ 


INFOW 
int 


BOOL 


int 


int 


char FAR * 


BOOL 


Meaning 


Maximum outbound size 
of a message for 
message socket types. 
There is no provision to 
determine the maximum 
inbound message size. 
Has no meaning for 


stream-oriented sockets. 


OOB data is being 
received in the normal 
data stream. 


Description of protocol 
information for the 
protocol that is bound to 
this socket. 


Buffer size for receives. 


The address to which 
this socket is bound can 
be used by others. Not 
applicable on ATM 
sockets. 


Total per-socket buffer 
space reserved for 
sends. This is unrelated 
to SO_MAX_MSG 
_SIZE or the size of a 
TCP window. 


The type of the socket 
(for example, 
SOCK_STREAM). 


An opaque data 


_ structure object 


containing configuration 
information of the 
service provider. 
Disables the Nagle 
algorithm for send 
coalescing. 


Default 


Implementation 
dependent 


FALSE 


Protocol 
dependent 


Implementation 
dependent 


FALSE 


Implementation 
dependent 


As created 
through socket. 


Implementation 
dependent 


_ Implementation 
- dependent 


(i) A service provider may silently ignore this option on WSPSetSockOpt and return a constant value for 
WSPGetSockOpt, or it may accept a value for WSPSetSockOpt and return the corresponding value in eee 
without using the value in any way. 


Note 


Get 
only 


Get 


only 


(i) 
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Summary of Socket loctl Opcodes 
The socket IOCTL opcodes for Windows Sockets 2 are summarized in the following 
table. More detailed information is provided in section 4 under WSPloctl. There are 
other new protocol-specific IOCTL opcodes that can be found in the protocol-specific 


annex. 
Opcode 
FIONBIO 


FIONREAD 


SIOCATMARK 


SIO ASSOCIATE HANDLE ~ 


SIO_ENABLE_CIRCULAR_ 
QUEUEING 


SIO_FIND_ ROUTE 
SIO_FLUSH 


SlO_GET_BROADCAST _ 
ADDRESS 


SIO_GET_QOS 
SIO_GET_GROUP_QOS 


SIO_MULTIPOINT_ 
LOOKBACK © 


Input type 


Unsigned 
long 


<Not used> 


<Not used> | 


Companion 
API 
dependent 


<Not used> 


SOCKADDR 


structure 


<Not used> 


<Not used> 


<Not used> 


<Not used> 
BOOL 


Output type 


<Not used> 


Unsigned long 


BOOL 


<Not used> 


<Not used> 


<Not used> 


<Not used> 


SOCKADDR 


structure 


QOS 


QOS 


<Not used> 


Meaning 


Enables or disables 
nonblocking mode on the 
socket. 


Determines the amount of 
data that can be read 
atomically from the socket. 
Determines whether or not all _ 
OOB data has been read. 
Associates the socket with 
the specified handle of a 
companion interface. 


Enables circular queuing. 


Requests the route to the 
specified address to be 
discovered. 


Discards current contents of 
the sending queue. 

Retrieves the protocol- 
specific broadcast address to 
be used in WSPSendTo. 
Retrieves current flow | 
specification(s) for the socket. 
Reserved. | 


Controls whether data sent in 


a multipoint session will also 
be received by the same 
socket on the local host. 
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(continued) 
Opcode 


SIO MULTICAST SCOPE | 


SIO_SET_QOS 


SlO_SET_GROUP_QOS 
SIO_TRANSLATE_HANDLE 


SIO_ROUTING_INTERFACE_ 


QUERY 


SIO_ROUTING_INTERFACE_ 


CHANGE 


SIO_ADDRESS_LIST_QUERY 


SIO_ADDRESS_LIST_ 
CHANGE 


SIO_QUERY_PNP_TARGET_ 


HANDLE 


Input type 


int 


QOS 


QOS 
int 


SOCKADDR 


SOCKADDR 


<Not used> 


<Not used> 


<Not used> 


Summary of SPI Functions 


The SPI functions for Windows Sockets 2 are summarized in the following tables. 


Output type 


<Not used> 


<Not used> 


<Not used> 


Companion- 
API 
dependent 


SOCKADDR 


<Not used> 


SOCKET_ 
ADDRESS _ 
LIST 


<Not used> 


SOCKET 


Generic Data Transport Functions 
This section lists the Data Transport functions exposed by Ws2spi.h. 


Meaning 


Specifies the scope over 
which multicast transmissions 
will occur. | 
Establishes new flow 
specification(s) for the socket. 
Reserved. 

Obtains a corresponding 
handle for socket s that is 
valid in the context of a 
companion interface. 

Obtains the address of the 
local interface that should be 


_used to send to the specified 


address. 


Requests notification of 
changes in information 
reported through 
SIO_ROUTING_ 
INTERFACE_QUERY for the 
specified address. 


Obtains the list of addresses 
to which the application can 
bind. 


Requests notification of 
changes in information 
reported through 
SIO_ADDRESS_LIST__ 
QUERY 


Obtains socket descriptor of 
the next provider in the chain 
on which current socket 
depends in regards to PnP. 


Function 


WSPAccept 


WSPAsyncSelect | 
WSPBind 
WSPCancelBlockingCall 


WSPCleanup 


WSPCloseSocket 


~ WSPConnect 


WSPDuplicateSocket 


WSPEnumNetworkEvents 
WSPEventSelect 
WSPGetOverlappedResult 
WSPGetPeerName 


WSPGetSockName 


_ WSPGetSockOpt 
WSPGetQOSByName 


WSPloctl 
WSP JoinLeaf 
WSPListen 


WSPRecv 
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Description 


An incoming connection is acknowledged and 
associated with an immediately created socket. The 
original socket is returned to the listening state. This 
function also allows for conditional acceptance. 


Performs asynchronous version of WSPSelect. 
Assigns a local name to an unnamed socket. 


Cancels an outstanding blocking Windows 

Sockets call. 

Signs off from the underlying Windows Sockets 
service provider. 

Removes a socket from the per-process object 
reference table. Only blocks if SO_LINGER is set with 
a nonzero time-out on a blocking socket. 

Initiates a connection on the specified socket. This 
function also allows for exchange of connect data and 
QOS specification. 


~ Returns a WSAPROTOCOL_INFOW structure that 


can be used to create a new socket descriptor for a 
shared socket. 


Discovers occurrences of network evenis. 
Associates network events with an event object. 
Gets completion status of overlapped operation. 


Retrieves the name of the peer connected to the 
specified socket. 


Retrieves the local address to which the specified 
socket is bound. 


Retrieves options associated with the specified socket. 


Supplies QOS parameters based on a well-known 
service name. 


Provides control for sockets. 
Joins a leaf node into a multipoint session. 


Listens for incoming connections on a specified 
socket. 

Receives data from a connected or unconnected 
socket. This function accommodates scatter/gather 
I/O, overlapped sockets, and provides the flags 
parameter as IN/OUT. — 
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(continued) 
Function 


WSPRecvDisconnect 


WSPRecvFrom 


WSPSelect 
WSPSend 


WSPSendDisconnect 


WSPSendTo 


WSPSetSockOpt 
WSPShutdown 
WSPSocket 


WSPStartup 


Description 


Terminates reception on a socket, and retrieve the 
disconnect data if the socket is connection-oriented. 
Receives data from either a connected or 
unconnected socket. This function accommodates 
scatter/gather I/O, overlapped sockets and provides 
the flags parameter as IN/OUT. — | 
Performs synchronous |/O multiplexing. 

Sends data to a connected socket. This function also 
accommodates scatter/gather I/O and overlapped 
sockets. . 

Initiates termination of a socket connection and 
optionally send disconnect data. 

Sends data to either a connected or unconnected 
socket. This function also accommodates 
scatter/gather I/O and overlapped sockets. 

Stores options associated with the specified socket. 
Shuts down part of a full-duplex connection. 

A socket creation function which takes a 
WSAPROTOCOL_INFOW structure as input and 
allows overlapped sockets to be created. 

Initializes the underlying Windows Sockets service 
provider. 


Upcalls Exposed by Windows Sockets 2 DLL 


This section lists the upcalls that service providers may make into the Windows Sockets 
client. Service providers receive an upcall dispatch table as a parameter to 
WSPStartup(), and use entries in this table to make the upcalls. Therefore, a client does 
not need to export its WPU functions. 


It is not mandatory that providers use all of these upcalls. The following table indicates 
which upcalls must be used and which are optional. 


Function 


WPUCloseEvent 


WPUCloseSocketHandle 


WPUCloseThread 


WPUCompleteOverlappedRequest 


WPUCreateEvent 


WPUCreateSocketHandle 


WPUFDIsSet | 
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Description 


Closes an open 


event object handle. 


Closes a socket 
handle allocated by 
the Windows 
Sockets DLL. 


Closes a thread ID 
for an internal 
service thread. 


Delivers overlapped 
I/O completion 
notification where 
the completion 
mechanism is 
something other 
than user 

mode APC. 


Creates a new 
event object. 


Creates a new 
socket handle for 
nonlFS providers. 


Checks the 
membership of the 
specified socket 
handle. 


Status 


Optional. 


Required. 


Optional. 


Required 
for nonIFS 
providers. 


Optional. | 


Meaning 


The provider may 
use an appropriate 
OS. call instead. 


The Ws2_32.dll 
needs to query 
and/or modify 
internal state 
information 
associated with the 
socket handle. 


The provider may 
use an appropriate 
OS call instead. 


The Ws2_32.dll 
needs to query 
and/or modify 
internal state 
information 


~ associated with the | 


socket handle. 


This is just a 


convenience — 
function that knows 
how to dig through 
FD SET structures. 
A providermay 
need to dig through 
these structures 
explicitly anyway. 

~ (continued) 
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(continued) 
Function 


WPUGetProviderPath 


WPUModifylFSHandle 


WPUPostMessage 


WPUQueryBlockingCallback 


WPUQuerySocketHandleContext 


WPUQueueApc 


Description 


Retrieves the DLL 
path for the 
specified provider. 


Receives a 
(possibly) modified 
IFS handle from the 
Windows 

Sockets DLL. 


Performs the 
standard 
PostMessage 
function in a way 
that maintains 
backward 
compatibility. 
Returns a pointer to 
a thread’s blocking 
hook function. 


Gets a socket’s 
context value 
(nonlFS 
providers only). 


Queues a user- 
mode APC to the 
specified thread. 


Status 


Required. 


Required 
for IFS 
providers. 


Required. 


Required. 


Required 
for nonIFS 
providers. 


Optional. 


Meaning 


Only the 
~ Ws2_32.dll would 


know where an 
adjacent protocol 
layer (potentially 
from another 
vendor) has been 
installed. 


The Ws2_32.dll 
needs to query 
and/or modify 
internal state 
information 
associated with the 
socket handle. 


Windows NT/2000 
only. Windows 95 
allows post 
message from 
kernel mode. 


There is no 
corresponding OS 
functionality. Only 
the Ws2_32.dll has 
the information to 
accomplish this. 


The Ws2_32.dll 
needs to query 


-and/or modify 


internal state 
information 
associated with the 
socket handle. 


The 


QueueUserApc 
may also be used. 


Chapter 10 Winsock 2 SPI Overview 471 


Function 7 Description Status Meaning 
WPUResetEvent Resets an event Optional. The provider may 
object. 7 use an appropriate 
— OS call instead. 
WPUSetEvent Sets an event Optional. The provider may 
object. — use an appropriate 


OS call instead. 


Installation and Configuration Functions 


The following functions are implemented in the Ws2_32.dll, and are intended to be used 
by applications that install Windows Sockets transport and name space service providers 
on a machine. These functions neither affect currently running applications, nor are the 
changes made by these functions visible to currently running applications. 


For all providers, a provider identifier is a GUID which is generated by the developer of 
_ the provider (using the Uuidgen.exe utility) and supplied to Ws2_32.dll. 7 


Function _ Description 

WSCDeinstallProvider . Removes a service provider from the registry. 

WSCEnumProtocols 7 Retrieves information about available transport 
| protocols. 

WSCinstallProvider Registers a new service provider. 


Name Resolution Service Provider Requirements 


The following sections provide a description of each of the functional areas that name 
space providers are required to implement. Where appropriate, implementation 
considerations and guidelines are also ineicaien | 


Summary of Namespace Provider Functions 


The namespace service provider functions can be grouped into five categories: 


e Namespace provider configuration sand installation) 
e Provider initialization 
-e Service installation | 

e Client queries 

) Helper functions (and macros) 


The following sections identity the functions in each ae and mery describe their 
nee use. >. Key data structures are also described. 
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Namespace Provider Configuration and Installation 
e WSClinstallINameSpace 

e WSCUnIinstallNameSpace 

e WSCEnableNSProvider 


As mentioned previously, the installation application for a namespace provider must call 
WSClnstallNameSpace to register with the Ws2_32.dll and supply static configuration 
information. The Ws2_32.dll uses this information to accomplish its routing function and 
in its inplementation of WSAEnumNameSpaceProviders. The | 
WSCuUninstallNameSpace function is used to remove a name space provider from the 
registry, and the WSCEnableNSProvider function is used to toggle a provider between 
the active and inactive states. 


The results of these three operations are not visible to applications that are currently 
loaded and running. Only applications that begin executing after these operations have 
occurred will be affected by them. 


This architecture explicitly supports the instantiation of multiple name space providers 
within a single DLL, however each such provider must have a unique name space 
provider identifier (GUID) allocated, and a separate call to WSCinstallNameSpace must 
occur for each instantiation. Such a provider can determine which instantiation is being 
invoked because the namespace provider (NSP) identifier appears as a parameter in 
every NSP function. : 


Namespace Provider Initialization and Cleanup 
e NSPStartup 
e NSPCleanup 


As is the case for the transport SPI, a namespace provider is initialized with a call to 
NSPStartup and is terminated with a final call to NSPCleanup. Calls to the startup 
function may be nested, but will be matched by corresponding calls to the cleanup 


function. A provider should employ reference counting to determine when the final call to 


NSPCleanup has occurred. 


Service Installation in the Windows Sockets 2 SPI 
¢ NSPinstallServiceClass 

e NSPRemoveServiceClass 

e NSPSetService 


When the required service class does not already exist, a namespace SPI client uses 
NSPinstallServiceClass to install a new service class by supplying a service class 
name, a GUID for the service class identifier, and a series oo WSANSCLASSINFO 
structures. These structures are each specific to a particular name space, and supply © 
common values such as recommended TCP port numbers or Netware SAP Identifiers. 
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A service class can be removed by calling NSPRemoveServiceClass and supplying the 
GUID corresponding to the class identifier. 


Once a service class exists, specific instances of a service can be installed or removed 
via NSPSetService. This function takes a WSAQUERYSET structure as an input 
parameter along with an operation code and operation flags. The operation code 
indicates whether the service is being installed or removed. The WSAQUERYSET 
structure provides all of the relevant information about the service including service class 
identifier, service name (for this instance), applicable name space identifier and protocol 
information, and a set of transport addresses to which the service listens. 


Service Query 

e NSPLookupServiceBegin 
e NSPLookupServiceNext 
e NSPLookupServiceEnd 


A name service query involves a series of calls: NSPLookupServiceBegin, followed by 
one or more calls to NSPLookupServiceNext and ending with a call to 
NSPLookupServiceEnd. NSPLookupServiceBegin takes a WSAQUERYSET 
‘structure as input in order to define the query parameters along with a set of flags to 
provide additional control over the search operation. It returns a query handle which is 
used in the subsequent calls to NSPLookupServiceNext and NSPLookupServiceEnd. 


The name space SPI client invokes NSPLookupServiceNext to obtain query results, 
with results supplied in an client-supplied WSAQUERYSET buffer. The client continues 
to call NSPLookupServiceNext until the error code WSA_E_NO_MORE is returned 
indicating that all results have been retrieved. The search is then terminated by a call to 
NSPLookupServiceEnd. The NSPLookupServiceEnd function can also be used to 
cancel a currently pending NSPLookupServiceNext when called from another thread. 


In Windows Sockets 2, conflicting error codes are defined for WSAENOMORE (10102) 
and WSA_E_NO_MORE (10110). The error code WSAENOMORE will be removed in a 
future version and only WSA_E_NO_MORE will remain. Name space providers should 
switch to using the WSA_E_NO_MORE error code as soon as possible to maintain 
compatibility with the widest pees range of applications. 


Helper Functions in the SPI 
e NSPGetServiceClassinfo 


The NSPGetServiceClassinfo function retrieves service class schema information that 
has been retained by a name space provider. It is also used by the Windows Sockets 2 
DLL in its implementation of WSAGetServiceClassNameByClassld. 


_ The following macros from Winsock2.h are available and can aid in mapping between 
well known service classes and these name Spaces: 
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SVCID_TCP(Port) | Given a port for TCP/IP or UDP/IP or the 


SVCID_UDP(Port) object type in the case of Netware, 
SVCID_NETWARE(Object Type) returns the GUID. | 
IS_SVCID_TCP(GUID) Returns TRUE if the GUID is within the 
IS_SVCID_UDP(GUID) allowable range. 
IS_SVCID_NETWARE(GUID) 

PORT_FROM_SVCID_TCP(GUID) Returns the port or object type associated 
PORT_FROM_SVCID_UDP(GUID) with the GUID. 


SAPID_FROM_SVCID_NETWARE(GUID) 


Name Resolution Data Structures in the SPI 


There are several important data structures that are used extensively throughout the 
name resolution functions. These are described below. | 


¢ Query-Related Data Structures in the SPI 
e Service Class Data Structures in the SPI 


Query-Related Data Structures in the SPI 


The WSAQUERYSET structure is used to form queries for NSPLookupServiceBegin, 
and used to deliver query results for NSPLookupServiceNext. It is a complex structure 
since it contains pointers to several other structures, some of which reference still other 
structures. Figure 10-4 shows the relationship between al and the 
structures it references. 


Within the WSAQUERYSET structure, most of the members are self explanatory, but 
some deserve additional explanation. The dwSize will be filled in with 
sizeof(WSAQUERYSET), and can be used by name space providers to detect and 
adapt to different versions of the WSAQUERYSET structure that may appear over time. 


The dwOutputFlags member is used by a name space provider to provide additional 
information about query results. For details, see NSPLookupServiceNext. 


The WSAECOMPARATOR structure referenced by /pversion is used for both query 
constraint and results. For queries, the dwVersion member indicates the desired version 
of the service. The ecHow member is an enumerated type which specifies how the 
comparison will be made. The choices are COMP_EQUALS which requires that an exact 
match in version occurs, or COMP_NOTLESS which specifies that the service’s version 
number be no less than the value of dwVersion. | 


The interpretation of dwNameSpace and /pNSProviderld depends upon how the 
structure is being used and is described further in the individual function descriptions 
that utilize this structure. _ 
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Lv Service Instance Name 


WSAQUERYSET __ 
| ervice Class ID (GUID) 


dwOutputFiags . 4a : 
CO ee 
ipServiceClassid | ee 
Ipversion 


\ 


‘dwversion 
ecHow (equals, or not less than) 


dwNamesSpace 
JpNSProviderid 
lipszContext Rs oi 
dwNumberOfProtocols | as 
IpszQueryString 
dwNumberOfCsAdars 
ipcesaBuffer 

pBlob 


ae 
ieee 


uery String 


3 
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Yr, 
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SOCKADDR 
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Figure 10-4: The Data Structure and the Structures It References. 


The lpszContext member applies to hierarchical name spaces, and specifies the 
starting point of a query or the location within the hierarchy where the service resides. 
The general rules are: , 


e A value of NULL, blank (*’) will start the search at the default context. 
e Avalue of “\” starts the search at the top of the name space. 
e Any other value starts the search at the designated point. 


Providers that do not support containment may return an error if anything other than “” or 
_\” is specified. Providers that support limited containment, such as groups, should 
accept “, “\’, or a designated point. Contexts are name space specific. If dwNameSpace 
is NS_ALL, then only “ or “\” should be passed as the context since these are 
recognized by allname spaces. _ eh 


The lpszQueryString member is used to supply additional, name space-specific query 
information such as a string describing a well-known service and transport protocol 
name, as in “ftp/tcp”. 
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The AFPROTOCOLS structure referenced by /pafpProtocols is used for query purposes 
only, and supplies a list of protocols to constrain the query. These protocols are 
represented as (address family, protocol) pairs, since protocol values only have meaning 
within the context of an address family. 


The array of CSADDR_INFO structure referenced by /pcsaBuffer contains all of the 
information needed for either a service to use in establishing a listen, or a client to use in 
establishing a connection to the service. The LocalAddr and RemoteAddr members 
both directly contain a SOCKET_ADDRESS structure. A service would create a socket 
using the tuple (LocalAdoar.|pSockadar->sa_family, isocketType, iProtocol). lt would bind 
the socket to a local address using LocalAdar.|poSockaddr, and 
LocalAdar.|pSockaddrLength. The client creates its socket with the tuple 
(RemoteAdadr.|poSockadadr->sa_family, iSocketType, iProtocol), and uses the combination 
of RemoteAdor.|pSockaddr, and RemoteAdar.|pSockaddrLength when making a remote 
connection. 


Service Class Data Structures in the SPI 


When a new service class is installed, a WSASERVICECLASSINFO structure must be 
prepared and supplied. This structure also consists of substructures that contain a series 
of parameters that apply to specific name spaces. (See Figure 10-5.) 


Service Class ID(GUID) 


WSASERVICECLASSINFO _ 


_IpServiceCiassid : 


dwCount Service Class Name 
loClassinfos 


dwNameSpace 
dwValueType 
dwVaiueSize 
IpValue 


Figure 10-5: Service Class Data Structures. 


For each service class, there is a single WSASERVICECLASSINFO structure. Within 


the WSASERVICECLASSINFO structure, the service class’s unique identifier is 
contained in /pServiceClassid, and an associated display string is referenced by 
loServiceClassName. 
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The IpClassinfos member in the WSASERVICECLASSINFO structure references an 
array of WSANSCLASSINFO structures, each of which supplies a named and typed 
parameter that applies to a specified name space. Examples of values for the IlpszName 
member include: SAPID, TCPPORT, UDPPORT, etc. These strings are generally 
specific to the name space identified in dwNameSpace. Typical values for dwValueType 
might be REG_DWORD, REG_SZ, etc. The dwValueSize member indicates the length 
of the data item pointed to by /pValue. | 


The entire collection of data represented ina WSASERVICECLASSINFO structure is 
provided to each name space provider via NSPInstallServiceClass. Each individual 
name space provider then sifts through the list op WSANSCLASSINFO structures and 
retain the information applicable to it. This architecture also envisions the future 
existence of a special name space provider that would retain all of the service class 
schema information for all of the name spaces. The Ws2_32.dll would query this 
provider to obtain the WSASERVICECLASSINFO data needed to supply to name space 

_ providers when NSPLookupServiceBegin is invoked to initiate a query, and when 
NSPSetService is invoked to register a service. Name space provider should not rely on 
this capability for the time being, and should instead have a provider-specific means to 
obtain any needed service class schema information. In the absence of a provider that 
stores all service class schema for all name spaces, the Ws2_32.dll will use 
NSPGetServiceClassinfo to obtain such information from each individual name space 
provider. | 


Compatible Name Resolution for TCP/IP | in the Windows 
Sockets 1. 1 SPI 


Windows Sockets 1.1 defined a number of routines that were used for name resolution 
with TCP/IP networks. These are customarily called the getXbyY functions and include 
the following. 


gethostname 
gethostbyaddr 
gethostbyname 
getprotobyname 
getprotobynumber 
getservbyname 
getservbyport 


| Asynchronous versions of these functions were also defined. 


WSAAsyncGetHostByAddr 
WSAAsyncGetHostByName 
WSAAsyncGetProtoByName 
WSAAsyncGetProtoByNumber 
WSAAsyncGetServByName 
WSAAsyncGetServByPort © 
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_ These functions are specific to TCP/IP networks and developers of protocol-independent 


applications are discouraged from continuing to utilize these transport-specific functions. 
However, to retain strict backward compatibility with Windows Sockets 1.1, all of the 
above functions continue to be supported as long as at least one name space provider is 
present that supports the AF_INET address family. 


The Ws2_32.dll implements these compatibility functions in terms of the new, protocol- 
independent name resolution facilities using an appropriate sequence of 
WSALookupServiceBegin, WSALookupServiceNext, WSALookupServiceEnd 
function calls. The details of how the getXbyY functions are mapped to name resolution 
functions are provided below. The Ws2_32.dll handles the differences between the 
asynchronous and synchronous versions of the getXbyY functions, so that only the 
implementation of the synchronous getXbyY functions are discussed. 


Basic Approach for getXbyY in the SPI 


Most getXbyY functions are translated by Ws2_32.dll to a WSALookupServiceBegin, 
WSALookupServiceNext, WSALookupServiceEnd sequence that uses one of a set of 
special GUIDs as the service class. These GUIDs identify the type of getXbyY operation 
that is being emulated. The query is constrained to those NSPs that support AF_INET. 
Whenever a getXbyY function returns a HOSTENT or SERVENT structure, the 
Ws2_32.dll will specify the LUP_RETURN_BLOB flag in WSALookupServiceBegin so 
that the desired information will be returned by the NSP. These structures must be 
modified slightly in that the pointers contained within must be replaced with offsets that 
are relative to the start of the blob’s data. All values referenced by these pointer 


members must, of course, be completely contained within the blob, and all strings are 


ASCII. 


getprotobyname and getprotobynumber Functions in the SPI 


These functions are implemented within Ws2_32.dll by consulting a local protocols 
database. They do not result in any name resolution query. 


getservbyname and getservbyport Functions in the SPI 


The WSALookupServiceBegin query uses SVCID_INET_SERVICEBYNAME as the 
service class GUID. The /oszServicelnstanceName parameter references a string which 
indicates the service name or service port, and (optionally) the service protocol. The 
formatting of the string is illustrated as ftp/tcp or 21/tcp or just ftp. The string is not case 
sensitive. The slash mark, if present, separates the protocol identifier from the preceding 
part of the string. The Ws2_32.dll will specify LUP_RETURN_BLOB and the NSP will 
place a SERVENT structure in the blob (using offsets instead of pointers as described 
above). NSPs should honor these other LUP_RETURN_* flags as well. 
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Flag Description 


LUP_RETURN_NAME Returns the s_name member from SERVENT structure in 
lpszServiceinstanceName. 


LUP_RETURN_TYPE Returns canonical GUID in /pServiceClassid It is understood © 
that a service identified as ftp or 21 may be on another port 
according to locally established conventions. The s_port 

_member of the SERVENT structure should indicate where the 
service can be contacted in the local environment. The 
canonical GUID returned when LUP_RETURN_TYPE is set 
should be one of the predefined GUIDs from svcs.h that 
corresponds to the port number indicated in the SERVENT 
structure. 


gethostbyname Function in the SPI 


The WSALookupServiceBegin query uses SVCID_ INET_ HOSTADDRBYNAME as the 
service class GUID. The host name is supplied in joszServicelnstanceName. The 
Ws2_32.dll specifies LUP_RETURN_BLOB and the NSP places a HOSTENT struct in 
the blob (using offsets instead of pointers as described above). NSPs should honor 
these other LUP_RETURN_* flags as well. 


Flag Description 


LUP_RETURN_NAME _ Returns the h_name member from HOSTENT structure in 
3 loszServiceInstanceName. | 
LUP_RETURN_ADDR Returns addressing information from HOSTENT in 
CSADDR_INFO structures, port information is defaulted to 
zero. Note that this routine does not resolve host names — 
consisting of a dotted internet address. 


gethostbyaddr Function in the SPI 


The WSALookupServiceBegin query uses SVCID_INET_ HOSTNAMEBYADDR as the 
service class GUID. The host address is supplied in jpszServiceinstanceName as a 
dotted internet string (for example, 192.9.200.120). The Ws2_32.dll specifies — 
LUP_RETURN_BLOB and the NSP places a HOSTENT structure in the blob (using 
offsets instead of pointers as described above). NSPs should honor these other 

LUP_ RETURN — flags as well. 


Flag | Description 


| LUP_RETURN_NAME Returns the h_name member from HOSTENT structure in 
on a3 bey at IpszServiceinstanceName. x , | 
7 LUP_RETURN_ADDR Returns addressing information from HOSTENT i in 
ees | 3 _  CSADDR_ INFOS structures, port information is defaulted - 
to zero. 
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gethostname Function in the SPI 


The WSALookupServiceBegin query uses SVCID_LHOSTNAME as the service class 
GUID. If joszServiceinstanceName is NULL or references a NULL string (that is “’), the 

| local host is to be resolved. Otherwise, a lookup on a specified host name shall occur. 
For the purposes of emulating gethostname the Ws2_32.dll will specify a null pointer for 
lpszServiceInstanceName, and specify LUP_RETURN_NAME so that the host name is 
returned in the joszServicelnstanceName parameter. If an application uses this query 
and specifies LUP_RETURN_ADDR then the host address will be provided ina 
CSADDR_INFO structure. The LUP_RETURN_BLOB action is undefined for this query. 
Port information will be defaulted to zero unless the /joszQueryString references a 
service such as ftp, in which case the complete transport address of the indicated 
service will be supplied. 


sample Code for a Service Provider 


This section contains a source code sample that demonstrates how to implement the 
GetXbyY functions using the new, protocol-independent RNR functions. A developer 
should implement these functions as a starting point. To comply with the Windows 
Sockets specification, many more functions are needed. 


Important The following code is not guaranteed to compile. | 
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The interface definition may be imported into a C or C++ program by means of the 
include file Sporder.h. The entry point may be linked by means of the lib file Sporder.lib. 
The actual procedure specification is given in the following section. 


Windows Sockets SPI Header File - Ws2spi.h 
The function prototypes and structures in this document can be found in Ws2spi.h. 


New versions of Ws2spi.h will appear periodically as new identifiers are allocated by the 
Windows Sockets Identifier Clearinghouse. The clearinghouse can be reached through 
the world wide web: 


http://www. stardust.com/winsock/ 


Developers are urged to stay current with successive revisions of Ws2spi.h as they are 
made available by the clearinghouse. 
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Winsock 2 SPI Reference 


Winsock 2 SPI Reference 


NSPCleanup 


The NSPCleanup function terminates the use of a particular Windows Sockets name 
space service provider. 


Parameters 


lpProviderld 
[in] Pointer to the GUID of the name-space provider that is to be terminated. 


Return Values 

lf no error occurs, NSPCleanup returns a value of NO_LERROR (zer0). Otherwise, 
SOCKET_ERROR (-1) is returned and the provider must set the appropriate error code 
age SetLastError. 


~ Remarks 


The NSPCleanup function is called when an application is finished using a Windows 
Sockets name space service provider. The NSPCleanup function deregisters 

a particular name-space provider and allows the transport service provider to free any 
of the name-space provider's allocated resources. 


The NSPStartup function must be called successfully before using any name-space 
providers. It is permissible to make more than one NSPStartup call. However, foreach — 
NSPStartup call, a corresponding NSPCleanup call must also be issued. Only the final 
NSPCleanup for the service provider does the actual cleanup; the preceding. calls simply 
decrement an internal reference count in the service provider. 


This function should not return until the name space service provider DLL can 
be unloaded from memory. 


498 


Volume 1 Winsock and QOS 


Error Codes 
Error code © Meaning 
WSAEINVAL The /pProviderld does not specify a valid 


provider. 


WSA_NOT_ENOUGH_MEMORY Not enough free memory available to perform 
this operation. 


NSPGetServiceClassinfo 


The NSPGetServiceClasslinfo function retrieves all the pertinent class information 
schema) pertaining to the name-space provider. This call retrieves any name space- 
specific information that is common to all instances of the service, including connection 

information for SAP, or port information for SAP or TCP. 


Parameters 


lpProviderld 


[in] Pointer to the GUID of the specific name-space provider from which the service 
class schema is to be retrieved. 


lpdwBufSize 
[in] Number of bytes contained in the buffer pointed to by /oServiceClassinfo on input. 
Alternately, if the function fails and the error is WSAEFAULT, /odwBufSize contains 


the minimum number of bytes to pass for the /oServiceClassinfo to retrieve the record 
on output. 


lpServiceClassInfo 
[in] Returns service class to name space-specific mapping information. 
The /pServiceClassid parameter must be filled in to indicate which 
WSASERVICECLASSINFOW record should be returned. 


Return Values 


If no error occurs, the NSPGetServiceClassInfo function returns NO_ERROR (zero). 


Otherwise, SOCKET_ERROR (-—1) is returned and it must set the appropriate error code 
using SetLastError. | | | 
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Remarks 


The W2_32.dll uses this function to implement the 
WSAGetServiceClassNameByClassld function, as well as to retrieve the name space 
specific information passed into the NSPLookupServiceBegin and NSPSetService. 


Error Codes 
Error code Meaning 
WSAEACCES Calling routine does not have sufficient 
privileges to access the information. 
WSAEFAULT The IpServiceClass buffer was too small 
to contain a WSASERVICECLASSINFOW. 
WSAEINVAL Specified service class identifier or name- 
| space—provider identifier is invalid. 
WSATYPE_NOT_FOUND Specified class was not found in any of the 


name spaces. 


WSA_NOT_ENOUGH_MEMORY Not enough free memory available to perform 
this operation. 


Version: Requires Windows Sockets 2. 0. 
Header: Declared in Ws2spi.h. 


NSPinstallServiceClass 


The NSPInstallServiceClass function registers service class schema within the name- 
space providers. 


The schema includes the class name, class identifier, and any name space-specific type 
information that is common to all instances of the service, such as SAP identifier 

or object identifier. A dynamic name-space provider is expected to store any class 
information associated with that name space. Other name-space Bievice = should | 

do whatever makes sense. 


Parameters 

IpProviderld 
[in] Pointer to the GUID of the specific name- space provider that this service class 
schema | is being registered i in. 
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lpServiceClassinfo 
[in] Contains service class schema information. 


Return Values 


The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-—1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Remarks 


Name space providers are encouraged but not required to store information that 
is specific to the name space they support. 


Error Codes 

Error code Meaning 

WSAEACCES Calling routine does not have sufficient privileges 
to perform this operation. 

WSAEALREADY Service class information has already been 
registered for this service class identifier. 
To modify service class information, first use 
NSPRemoveServiceClass, then reinstall with 
updated class information data. 

WSAEINVAL Service class identifier was invalid or improperly 
structured. 

WSA_INVALID_- PARAMETER Name space provider cannot supply the requested 


class information. 


WSA_NOT_ENOUGH_MEMORY __ Not enough free memory available to perform this 
operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. — 


NSPLookupServiceBegin 


The WSALookupServiceBegin function initiates a client query that is constrained 
by the information contained within a WSAQUERYSET structure. 
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WSALookupServiceBegin only returns a handle, which should be used by subsequent 
calls to WSALookupServiceNext to get the actual results. Since this operation can not 
be canceled, it should be implemented to execute quickly. While it is acceptable 

to initiate a network query, this function should not require a response in order to return 

successfully. | 


Parameters 


lpProviderld 
[in] Contains the specific provider identifier that should be used for the query. 


loqsRestrictions 
[in] Contains the search criteria. See the following for more information. 


IpServiceClassInfo | 
[in] WSASERVICECLASSINFOW structure that contains all the schema information 
for the service. 


dwControlFlags 
[in] Controls the depth of the search. 


Value Meaning 

LUP_DEEP Query deep as opposed to just the first level. 

LUP_CONTAINERS — Return containers only. 

LUP_NOCONTAINERS Do not return any containers. 

LUP_FLUSHCACHE If the provider has been caching information, 
ignore the cache and go query the name space 
itself. 

LUP_FLUSHPREVIOUS Used as a value for the dwControlFlags argument 


in NSPLookupServiceNext. Setting this flag 
instructs the provider to discard the last result set, 
which was too large for the supplied buffer, and — 
move on to the next result set. 


LUP_NEAREST If possible, return results in the order of distance. 
The measure of distance is provider specific. 
LUP_RES_RESERVICE — Indicates whether prime response is in the remote 


or local part of CSADDR_INFO structure. 
The other part needs to be usable in either case. 
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(continued) 
Value © _ Meaning 
LUP_RETURN_ALIASES Any available alias information is to be returned 
in successive calls to NSPLookupServiceNext, 
and each alias returned will have the 
RESULT_IS_ALIAS flag set. 
LUP_RETURN_NAME Retrieves the name as lpszServicelnstanceName. 
LUP_RETURN_TYPE Retrieves the type as /oServiceClassld. 
LUP_RETURN_WSAVERSION _ Retrieves the version as /pVersion. 
LUP_RETURN_COMMENT Retrieves the comment as /joszComment. 
LUP_RETURN_ADDR Retrieves the addresses as /pcsaBuffer. 
LUP_RETURN_BLOB Retrieves the private data as /pBlob. 
LUP_RETURN_ALL Retrieves all the information. | 
IphLookup 


[out] Handle to be used in subsequent calls to NSPLookupServiceNext in order 
to retrieve the results set. 


Return Values 


The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Remarks . 

lf LUP_CONTAINERS is specified in a call, all other restriction values should be 
avoided. If any are supplied, it is up to the name service provider to decide if it can 
support this restriction over the containers. If it cannot, it should return an error. 


Some name service providers may have other means of finding containers. For example, 
containers can all be of some well-known type, or of a set of well-known types, and 
therefore a query restriction could be created for finding them. No matter what other 
means the name service provider has for locating containers, LUP_CONTAINERS and 
LUP_NOCONTAINERS take precedence. Hence, if a query restriction is given that 
includes containers, specifying LUP_NOCONTAINERS will prevent the container items 
from being returned. Similarly, no matter the query restriction, if LUP_CONTAINERS 

is given, only containers should be returned. If a name space does not support 
containers and LUP_CONTAINERS is specified, it should simply return WSANO_DATA. 


The preferred method of obtaining the containers within another container, is the call: 
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followed by the requisite number of NSPLookupServiceNext calls. This will return all 
containers contained immediately within the starting context; that is, it is not a deep 
query. With this, one can map the address space structure by walking the hierarchy, 
perhaps enumerating the content of selected containers. Subsequent uses 

of NSPLookupServiceBegin use the containers returned from a previous call. 


Forming Queries 


As mentioned above, a WSAQUERYSET structure is used as an input parameter 

to NSPLookupServiceBegin in order to qualify the query. The following table indicates 
how the WSAQUERYSET is used to construct a query. When a member is marked 

as (Optional) a NULL pointer can be supplied, indicating that the parameter will not be — 
used as a search criteria. See Query-Related Data Structures for additional information. 


WSAQUERYSET member name Query interpretation 


dwSize Will be set to sizeof(WSAQUERYSET). This is a versioning 
| mechanism. 
dwOuputFlags Ignored for queries. 
IpszServicelInstanceName (Optional) Referenced string contains service name. The 
semantics for wildcarding within the string are not defined, 
| but can be supported by certain name-space providers. 
IpServiceClassid (Required) GUID corresponding to the service class. 
IpVersion (Optional) References desired version number and provides 
| version comparison semantics (that is, version must match 
exactly, or version must be not less than the value supplied). 
lpszComment ~. Ignored for queries. | . 
dwNameSpace Identifier of a single name space in which to constrain the 
search, or NS_ALL to include all name spaces. 
lpNSProviderld (Optional) References the GUID of a specific name-space 
| | ; provider and limits the query to this provider only. | 
IpszContext | | (Optional) Specifies the starting point of the query 
ea: | in a hierarchical name space. 
dwNumberOfProtocols | Size of the protocol constraint array, can be zero. 
IpafpProtocols  —T (Optional) References an array ot AFPROTOCOLS structure. 
| Only services that utilize these protocols will be returned. 
It is legal for the value AF_UNSPEC to appear as a protocol 
family value, signifying a wildcard. Name space providers 
may supply information on any service that uses the 
- corresponding protocol, regardless of address family. 


lpszQueryString | (Optional) Some name spaces (such as whois++) support 


enriched SQL-like queries that are contained in a simple text 
string. This palettes is used to specify that string. 
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(continued) 


WSAQUERYSET member name Query interpretation 


dwNumberOfCsAddrs Ignored for queries. 
lpcsaBuffer Ignored for queries. 
IpBlob (Optional) Pointer to a provider-specific entity. 
Error Codes 
Error code Meaning 
WSAEINVAL One or more parameters were invalid for this 
provider or missing. 
WSANO_DATA Name was found in the database but it does not 


have the correct associated data being resolved 
for. 


WSASERVICE_NOT_FOUND No such service is known. The service cannot be 
| found in the specified name space. 


WSA_NOT_ENOUGH_MEMORY _ Not enough free memory available to perform this 
operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


NSPLookupServiceEnd 


The NSPLookupServiceEnd function is called to free the handle after previous calls 
to NSPLookupServiceBegin and NSPLookupServiceNext. 


It is possible to receive an NSPLookupServiceEnd call on another thread while 
processing an NSPLookupServiceNext. This indicates that the client has canceled. 
the request and the provider should close the handle and return from the 
NSPLookupServiceNext call as well, setting the last error to WSA_E CANCELLED. 


Parameters 
hLookup 
[in] Handle previously obtained by calling NSPLookupServiceBegin. 
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Return Values 

The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-—1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Remarks 

In Windows Sockets 2, conflicting error codes are defined for WSGAECANCELLED 
(10103) and WSA_E_ CANCELLED (10111). The error code WSAECANCELLED will 

be removed in a future version and only WSA_E_CANCELLED will remain. Name Space 
Providers should switch to using the WSA_E_CANCELLED error code as soon 

as possible to maintain compatibility with the widest possible range of applications. 


Error Codes 

Error code Meaning 

WSA_INVALID_HANDLE Handle is not valid. 

WSA_NOT_ENOUGH_MEMORY Not enough free memory available to perform 
: this operation. | | 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


NSPLookupServiceNext 


The NSPLookupServiceNext function is called after obtaining a handle from a previous 
call to NSPLookupServiceBegin in order to retrieve the requested service information. 


The provider will pass back a WSAQUERYSET structure in the /oqsResults buffer. 
The client should continue to call this function until it returns WSA_E_ NOMORE, 
indicating that all the WSAQUERYSET have been returned. 


Parameters 
hLookup | 
[in] Handle returned from the previous call to WSALookupServiceBegin. 
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dwControlFlags 
[in] Flags to control the next operation. Currently only LUP_FLUSHPREVIOUS 
is defined as a means to cope with a result set that is too large. If an application does 
not wish to (or cannot) supply a large enough buffer, setting LUP_FLUSHPREVIOUS 
instructs the provider to discard the last result set, which was too large, and move 
to the next set for this call. 


lodwBufferLength 
[in/out] On input, the number of bytes contained in the buffer pointed to 
by IpgsResults. On output, if the function fails and the error is WSAEFAULT, then 
it contains the minimum number of bytes to pass for the JoqgsResults to retrieve the 
_ record. 


logsResults 
[out] Pointer to a block of memory that will contain one result set 
ina WSAQUERYSET structure on return. 


Return Values 

The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-—1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Remarks | 

The dwControlFlags specified in this function and the ones specified at the time of 
NSPLookupServiceBegin are treated as “restrictions” for the purpose of combination. 
The restrictions are combined between the ones at NSPLookupServiceBegin time 
and the ones at NSPLookupServiceNext time. Therefore, the flags at 
NSPLookupServiceNext can never increase the amount of data returned beyond what 
was requested at NSPLookupServiceBegin, although it is not an error to specify more 
or less flags. The flags specified at a given NSPLookupServiceNext apply only 

to that call. | 


The dwControlFlags LUP_FLUSHPREVIOUS and LUP_RES_SERVICE are exceptions 
to the combined restrictions rule (because they are behavior flags instead of restriction 
flags).If either of these flags is used in NSPLookupServiceNext, they have their defined 
effect regardless of the setting of the same flags at NSPLookupServiceBegin. 


For example, if LUP_RETURN_VERSION is specified at NSPLookupServiceBegin, 
the service provider retrieves records including the version. If LUP_RETURN._ VERSION 
is not specified at NSPLookupServiceNext, the returned information does not include 
the version, even though it was available. No error is generated. 


_ Also for example, if LUP_RETURN_BLOB is not specified at NSPLookupServiceBegin 


but is specified at NSPLookupServiceNext, the returned information does not include 
the private data. No error is generated. 


Query Results 
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The following table describes how the query results are represented in the 
WSAQUERYSET structure. Refer to Query-Related Data Structures for additional 


information. 
WSAQUERYSET member name 


dwsSize 


dwOuputFlags 
IpszServicelnstanceName 
IpServiceClassid 
IpVersion 


IpszComment 
dwNameSpace ~ 
IpNSProviderld 


IpszContext 


dwNumberOfProtocols — 
IpafpProtocols 


IpszQueryString 


dwNumberOfCsAddrs 
lpcsaBuffer 


IpBlob 


Result interpretation 


Will be set to sizeof(WSAQUERYSET). This is used 
as a versioning mechanism. 


RESULT_IS_ALIAS flag indicates this is an alias result. 
References the string that contains the service name. 
GUID corresponding to the service class. 


References version number of the particular service 
instance. 


Optional comment string supplied by service instance. 
Name space in which the service instance was found. 


Identifies the specific name-space provider that supplied 
this query result. 


Specifies the context point in a hierarchical name space 
at which the service is located. 


Undefined for results. 


Undefined for results, all needed protocol information is 
in the CSADDR_INFO structures. | | | 


When dwControlFlags includes 


LUP_RETURN_QUERY_STRING, this member returns the 
unparsed remainder of the /pszServicelnstanceName 
specified in the original query. For example, in a name 
space that identifies services by hierarchical names that 
specify a host name and a file path within that host, the 
address returned might be the host address and the - 
unparsed remainder might be the file path. Ifthe 
IpszServicelnstanceName is fully parsed and 
LUP_RETURN_QUERY_STRING is used, this member 

is NULL or points to a zero-length string. 


Indicates the number of elements in the array 
of CSADDR_INFO structures. 


Pointer to an array of CSADDR_INFO structures, with one 
complete transport address contained within each element. 


(Optional) Pointer to a provider-specific entity. 
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Error Codes 
Error code 


WSA_E_NO_MORE 


WSA_E_CANCELLED 


WSAEFAULT 
WSAEINVAL 


WSA_INVALID_HANDLE 
WSANO_DATA 


WSASERVICE_NOT_FOUND 


WSA_NOT_ENOUGH_MEMORY 


Meaning 


There is no more data available. 


In Windows Sockets 2, conflicting error codes are defined 
for WSAENOMORE (10102) and WSA_E_NO_MORE 
(10110).The error code WSAENOMORE will be removed 

in a future version and only WSA_E_NO_MORE will remain. 
Name space providers should switch to using the 
WSA_E_NO_MORE error code as soon as possible 

to maintain compatibility with the widest possible range 

of applications. 


Call to NSPLookupServiceEnd was made while this call 
was still processing. The call has been canceled. The data 
in the joqgsResults buffer is undefined. 


In Windows Sockets 2, conflicting error codes are defined 
for WSAECANCELLED (10103) and WSA_E_CANCELLED 
(10111).The error code WSAECANCELLED will be 
removed in a future version and only WSA_E_CANCELLED 
will remain. Name space providers should switch to using 
the WSA_E_CANCELLED error code as soon as possible 
to maintain compatibility with the widest possible range 

of applications. 


The /oqsResults buffer was too small to contain 
a WSAQUERYSET set. 


One or more parameters were invalid or missing for this 
provider. 


Specified lookup handle is invalid. 


The name was found in the database but no data matching 
the given restrictions was located. 


No such service is known. The service cannot be found 
in the specified name space. 


Not enough free memory available to perform this operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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NSPRemoveServiceClass 


The NSPRemoveServiceClass function permanently removes a specified service class 
from the name space. 


Parameters 


IpProviderld | 
[in] Pointer to the GUID of the specific name-space provider that this service class 
schema is to be removed from. | 


IpServiceClassld 
[in] Pointer to the GUID for the service class to remove. 


Return Values 


The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Error Codes 

Error code Meaning 

WSATYPE_NOT_FOUND Specified class was not found in any of the name 
spaces. 

| ~WSAEACCES | Calling routine does not have sufficient privileges 

to remove the Service. 

WSA_INVALID_ PARAMETER Specified GUID was not valid. © 

WSAEINVAL Specified service class identifier GUID was not 
valid. | 

WSA_NOT_ENOUGH_MEMORY __ Not enough free memory available to perform this 

3 operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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NSPSetService 


The NSPSetService function registers or deregisters a service instance within 
a name space. 


Parameters 

lpProviderld 
[in] Pointer to the GUID of the specific name-space provider in which the service 
is being registered. 

lpServiceClassInfo 
[in] Contains service class schema information. 


loqsRegInfo 2.4. s+ : 
_ [in] Specifies property information to be updated upon registration. 


essOperation 
[in] Enumeration whose values include: 


RNRSERVICE_REGISTER 
Register the service. For SAP, this means sending out a periodic broadcast. 
This is an NOP for the DNS name space. For persistent data stores this means 


updating the address information. 


RNRSERVICE_DEREGISTER 
-Deregister the service. For SAP, this means stop sending out the periodic 
broadcast. This is an NOP for the DNS name space. For persistent data stores 
this means deleting address information. = 


RNRSERVICE_DELETE | 
Delete the service from dynamic name and persistent spaces. For 
services represented by multiple CSADDR_INFO structures (using the 
SERVICE_MULTIPLE flag), only the supplied address will be deleted, and 
this must match exactly the corresponding CSADD_INFO structure that 
was supplied when the service was registered. : 


dwControlFlags 
— [in] Set of control flags whose values include: 


SERVICE_MULTIPLE 
Controls scope of operation. A register or deregister invalidates all existing 


addresses before adding the given address set. When set, the action is only 
performed on the given address set. A register does not invalidate existing 
addresses and a deregister only invalidates the given set of addresses. 
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The available values for essOperation and dwControlFlags combine to give meanings 
as shown in the following table. 


Operation 


RNRSERVICE_ 


REGISTER 


RNRSERVICE_ 


REGISTER © 


RNRSERVICE _ 


DEREGISTER 


~RNRSERVICE_ 


DEREGISTER 


RNRSERVICE_ 


DELETE 


RNRSERVICE__ 


DELETE — 


Flags 


None 


SERVICE _ 


MULTIPLE 


None 


SERVICE __ 


MULTIPLE 


None 


~SERVICE_ 


MULTIPLE 


Return Values 
~ The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-1) if the routine fails and it must set the appropriate error code 

using SetLastError. 


Remarks | : 
SERVICE_ MULTIPLE lets an application manage its eee independently. 

This is useful when the application wants to manage its protocols individually or when 
the service resides on more than one machine. For instance, when a service uses more 
than one protocol, it may find that one listening socket aborts but the others remain 
operational. In this case, the service could deregister the aborted address without 
affecting the other addresses. 


Service already exists 


Overwrites the object. Uses only 
addresses specified. Object is 
REGISTERED. 


Updates object. Adds new 
addresses to existing set. Object 
is REGISTERED. 


Removes all addresses, but 
does not remove object from 
name space. Object is 


DEREGISTERED. 


Updates object. Removes only 
addresses that are specified. 
Only mark object as 


DEREGISTERED if no 


addresses are present. Does not 
remove from the name space. 


Removes object from the name 
space. 


Removes only addresses that 
are specified. Only removes 
object from the name space if no 
addresses remain. 


Service does not exist 


Creates a new object. Uses 
only addresses specified. 
Object is REGISTERED. 


Creates a new object. Uses 
all addresses specified. | 
Object is REGISTERED. 


WSASERVICE_ 
NOT_FOUND 


WSASERVICE__ 
NOT FOUND 


WSASERVICE_ 
NOT_FOUND 
WSASERVICE __ 
NOT_FOUND . 
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When using SERVICE_MULTIPLE, an application must not let stale addresses remain 
in the object. This can happen if the application aborts without issuing a DEREGISTER 
request. When a service registers, it should store its addresses. On its next invocation, 
the service should explicitly deregister these old stale addresses before registering new 


addresses. 


Service Properties 


The following table describes how service property data is represented in a 
WSAQUERYSET structure. Members labeled as (Optional) can be supplied with a NULL 


pointer. 


WSAQUERYSET 
member name 


dwSize 


DwOuputFlags 


LpszServiceinstanceName 


LpServiceClasslid 
LpVersion 
LpszComment 
DwNameSpace 
LpNSProviderld 


LpszContext 


DwNumberOfProtocols 
LpafpProtocols 
LpszQueryString 
DwNumberOfCsAddrs 


LpcsaBuffer 


LpBlob 


Service property description 

Must be set to sizeof(WSAQUERYSET). This 

is a versioning mechanism. 

Not applicable and ignored. 

Referenced string contains the service instance name. 
GUID corresponding to this service class. 

(Optional) Supplies service instance version number. 
(Optional) An optional comment string. 

Ignored for this operation. 


Ignored for this operation, provider identifier is contained | 
in the IpProviderld parameter. 


(Optional) Specifies the starting point of the query 
in a hierarchical name space. 


Ignored. 
Ignored. 
Ignored. 


Number of elements in the array of CSADDRO_INFO 
structures referenced by /pcsaBuffer. 


Pointer to an array of CSADDRO_INFO structures that 
contain the address[es] that the service is listening on. 


(Optional) Pointer to a provider-specific entity. 


- Note Itis acceptable for the iProtocol member of the CSADDR_INFO structure 


to contain the manifest constant IPROTOCOL_ANY, signifying a wildcard value. 
The name-space provider should substitute a value that is reasonable for the given 


address family and socket type. 
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Error Codes 
Error code Meaning 
-WSAEACCES | Calling routine does not have sufficient privileges 


| to install the service. 
WSAEINVAL | One or more parameters were invalid or missing 
: | for this provider. 
WSA_NOT_ENOUGH_MEMORY __ Not enough free memory available to perform this 
operation. 


WSASERVICE_NOT_FOUND No such service is known. The service cannot 
_ be found in the specified name space. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


NSPStartup 


_ The NSPStartup function retrieves the dynamic information about a provider, such 
as the list of the DLL entry points. 


This function is called by the client upon initialization. NSPStartup and NSPCleanup | 
must be called as pairs. All the NSP functions must be called from within 

an NSPStartup/NSPCleanup pair. WSC functions do not need to be called from 
within an NSPStartup/NSPCleanup pair either. 


Parameters 
IpProviderld 
[in] Indicates the desired provider for which to return the entry points: 


IpnspRoutines 
[out] Pointer to all the provider entry points. 


Data Types 


_ The following data types are 9 needed for this call. 


NSP_ROUTINE 
The NSP_ROUTINE structure contains information egarding all the functions | 
implemented Py a given provider. 
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cbSize 
Size of this structure. 


dwMajorVersion 
Major version of the service provider specification supported by this provider. 


dwMinorVersion 

Minor version of the service provider specification supported by this provider. 
*NSP*.* | 

Pointers to the various NSP functions. Every entry must point to a valid function. 


lf the provider does not implement this function, it should simply return 
WSAENOTIMPLEMENTED. 


Note In the header file this structure contains complete prototypes for all the NSP 
pointers. 


Return Values 


The function should return NO_ERROR (zero) if the routine succeeds. It should return 
SOCKET_ERROR (-—1) if the routine fails and it must set the appropriate error code 
using SetLastError. 


Error Codes 

Error Code | Meaning 

WSAEINVAL | One or more parameters were invalid or 
missing for this provider. — 

WSA_NOT_ENOUGH_MEMORY __ Not enough free memory available to 


perform this operation. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCloseEvent 


The WPUCloseEvent function closes an open event object handle. 


Parameters 


hEvent 
[in] Handle to an open event object. 


IpErrno | : 
[out] Pointer to the error code. 


Return Values 


If the function succeeds, the return value is TRUE. Otherwise, the return value is FALSE | 
and a specific error code is available in JpErrno. _ | it ene 


Error Codes — 7 
Error code Meaning 


WSA_INVALID_HANDLE The hEvent is not a valid event object handle. 


Version: Requires Windows Sockets 2.0. 
_Header: Declared in Ws2spi.h. 


WPUCreateEvent oe 3 


WPUCloseSocketHandle 


The WPUCloseSocketHandle function closes an existing socket handle. 
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Parameters 


Ss 
[in] Handle to socket created with WPUCreateSocketHandle. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WPUCreateSocketHandle returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /oErrno. 


Remarks 


The WPUCloseSocketHandle function closes an existing socket handle created 
by WPUCreateSocketHandle. This function removes the socket from Ws2_32.dll’s 
internal socket table. The owning service provider is responsible for releasing any 
resources associated with the socket. 


Error Codes 
Error code Meaning 


WSAENOTSOCK Descriptor is not a socket created by WPUCreateSocketHandle. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCreateSocketHandle 


WPUCloseThread 


The WPUCloseThread function closes a thread opened with a 
call to WPUOpenCurrentThread. _ | | | 
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Parameters 


lo Threadld 
[in] Pointer to a WSATHREADID structure that identifies the thread context. This 
structure must have been initialized by a previous call to WPUOpenCurrentThread. 


loErrno 
[out] Pointer to the error code. 


Return Values 


lf no error occurs, WPUOpenCurrentThread returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /pErrno. 


Remarks 


The WPUCloseThread function is used in a layered service provider to deallocate the 
resources that were initiated in a call by the WPUOpenCurrentThread function. 
The WSATHREADID structure in the /oThreadid is the thread to deallocate. 


Every call to WPUOpenCurrentThread must have a call to WPUCloseThread. These 
two functions are used when the overlapped functions, such as WSPSend, are called 
in a lower layer of the service provider than the current thread. 


Error Codes 
Error code | Meaning 
WSANOTINITIALISED =A successful WSPStartup call must occur before using this © 


function. 


ee 
5 

oy 
Be 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCloseThread, WPUOpenCurrentThread 


-WPUCompleteOverlappedRequest 


The WPUCompleteOverlappedRequest function performs overlapped I/O completion 
notification for overlapped I/O operations. | 


(continued) 
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(continued) 


Parameters 


s 
[in] Service provider socket created by WPUCreateSocketHandle. 


IpOverlapped — | 
[in] Pointer to a WSAOVERLAPPED structure associated with the overlapped 
I/O operation whose completion is to be notified. 


QweError | 
[in] Completion status of the overlapped I/O operation whose completion 
is to be notified. 


cbTransferred 
[in] Number of bytes transferred to or from client buffers (the direction of the transfer 
depends on the send or receive nature of the overlapped I/O operation whose 
completion is to be notified). 


IpErrno 
[out] Pointer to the error code resulting from execution of this function. 


Return Values 


If no error occurs, WPUCompleteOverlappedRequest returns zero and notifies 
completion of the overlapped I/O operation according to the mechanism selected 

by the client (Signals an event found in the WSAOVERLAPPED structure referenced 
by jpOverlapped and/or queues a completion status report to the completion port 
associated with the socket if a completion port is associated). Otherwise, 
WPUCompleteOverlappedRequest returns SOCKET_ERROR, and a specific 
error code is available in ipErmo. 


Remarks 


The WPUCompleteOverlappedRequest function performs overlapped I/O completion 
notification for overlapped I/O operations where the client-specified completion 
mechanism is something other than user mode—asynchronous elas li call (APC). 
This function can only be used for socket handles created | 

by WPUCreateSocketHandle. 


Note This function is different from other functions with the WPU prefix in that it is 
not accessed through the upcall table. Instead, it is exported directly by Ws2_32.dll. 
Service providers that need to call this function should link with WS2_32.lib or use 
appropriate operating system functions such as LoadLibrary and GetProcAddress 
to retrieve the function pointer. 
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The function WPUCompleteOverlappedRequest is used by service providers that 

do not implement Installable File System (IFS) functionality directly for the socket 
handles they expose. It performs completion notification for any overlapped I/O request 
for which the specified completion notification is other than a user-mode APC. 
WPUCompleteOverlappedRequest is supported only for the socket handles created 
by WPUCreateSocketHandle and not for sockets created by a service provider directly. 


If the client selects a user-mode APC as the notification method, the service provider 
should use WPUQueueApc or another appropriate operating system function to perform 
the completion notification. If user-mode APC is not selected by the client, a service 
provider that does not implement IFS functionality directly cannot determine whether 

or not the client has associated a completion port with the socket handle. Thus, it cannot 
determine whether the completion notification method should be queuing a completion 
status record to a completion port or signaling an event found in the 
WSAOVERLAPPED structure. The Windows Socket 2 architecture keeps track of any 
completion port association with a socket created by WPUCreateSocketHandle and can 
make a correct decision between completion port-based notification or event-based 
notification. 


When WPUCompleteOverlappedRequest queues a completion indication, it sets the 
InternalHigh member of the WSAOVERLAPPED structure to the count of bytes © 
transferred. Then, it sets the Internal member to some OS-dependent value other than 
the special value WSS_OPERATION_IN_PROGRESS. There may be some slight delay 
after WPUCompleteOverlappedRequest returns before these values appear, since 
processing may occur asynchronously. However, the InternalHigh value (byte count) — 

is guaranteed to be set by the time Internal is set. | 


WPUCompleteOverlappedRequest is available both on Windows® 95/98 and 
Windows NT®/Windows® 2000. It works as stated (performs the completion notification 
as requested by the client) whether or not the socket handle has been associated with 
a completion port. a 


Interaction with WSPGetOverlappedResult 


The behavior of WPUCompleteOverlappedRequest places some constraints on how 
a service provider implements WSPGetOverlappedResult since only the Offset and 
OffsetHigh members of the WSAOVERLAPPED structure are exclusively controlled 
by the service provider, yet three values (byte count, flags, and error) must be retrieved 
from the structure by WSPGetOverlappedResult. A service provider may accomplish 
this any way it chooses as long as it interacts with the behavior 

of WPUCompleteOverlappedRequest properly. However, a typical. 

implementation is as follows: 


¢ At the start of overlapped processing, the service provider sets Internal 
to woo eee IN_-PROGRESS. : 
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e When the I/O operation has been completed, the provider sets OffsetHigh to the 
Windows Socket 2 error code resulting from the operation, sets Offset to the flags 
resulting from the I/O operation, and calls WPUCompleteOverlappedRequest, 
passing the transfer byte count as one of the parameters. 
WPUCompleteOverlappedRequest eventually sets InternalHigh to the transfer byte 
count, then sets Internal to a value other than WSS_OPERATION_IN_PROGRESS. 


e When WSPGetOverlappedResult is called, the service provider checks Internal. 
If itis WSS_OPERATION_IN_PROGRESS, the provider waits on the event handle 
in the hEvent member or returns an error, based on the setting of the FWAIT flag 
of WSPGetOverlappedResult. If not in progress, or after completion of waiting, the 
provider returns the values from InternalHigh, OffsetHigh, and Offset as the transfer 
count, operation result error code, and flags respectively. 


Error Codes 
Error code Meaning 


WSAEINVAL Socket is not a socket created by WPUCreateSocketHandle. 


WSPGetOverlappedResult, WPUCreateSocketHandle, WPUQueueApc 


WPUCreateEvent 


The WPUCreateEvent function creates a new event object. 


Parameters 


lpErrno 
[out] Pointer to the error code. 


Return Values | | 
If no error occurs, WPUCreateEvent function returns the handle of the event object. 


Otherwise, the return value is WSA_INVALID_EVENT and a specific error code 
is available in /oErrno. 


Remarks 


The event object created by this function is manual reset with an initial state 
of nonsignaled. If a Win32 service provider wants auto reset events, it can call the 
Win32 CreateEvent function directly. For more information, see CreateEvent. 
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Error Codes 
Error code Meaning 


WSA_NOT_ENOUGH_MEMORY __ Not enough free memory available to create the 
event object. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCloseEvent | 


WPUCreateSocketHandle 


The WPUCreateSocketHandle function creates a new socket handle. 


Parameters 


dwCatalogEntryld 
[in] Descriptor identifying the calling service provider. 


dwContext 
[in] Context value to associate with ner new socket handle. 


lpErrno” 
[out] Pointer to the error code. 


Return Values 
If no error occurs, WPUCreateSocketHandle returns the new socket handle. Otherwise, 
it returns INVALID -SOCKET, and a specific error code is available in ae 


~ Remarks 

The WPUCreateSocketHandle function creates a new socket handle for the specified 
provider. The handles created by WPUCreateSocketHandle are indistinguishable from 
true file system handles. This is significant in two respects. First, the Windows Socket 2 
architecture takes care of redirecting the file system functions ReadFile and WriteFile 
to this service providers WSPRecv and WSPSend functions, respectively. Second, 


522 


Volume 1 Winsock and QOS 


in operating systems that support completion ports, the Windows Sockets 2 architecture 
supports associating a completion port with the socket handle and using it to report 
overlapped I/O completion. | 


Note That the mechanism for redirecting ReadFile and WriteFile necessarily involves 
a user-to-kernel transition to get to the redirector, followed by a kernel-to-user transition 
to get to WSPRecv or WSPSend. On return, these transitions are retraced in reverse. 
This can be a significant performance penalty. Any service provider that uses 
WPUCreateSocketHandle to create its socket handles should not set 
XP1_IFS_HANDLES in its WSAPROTOCOL_INFOW structure. Clients should take the 
absence of XP1_IFS_HANDLES as guidance to avoid the use of ReadFile 

and WriteFile. 


There is no exceptional performance penalty for using the completion port mechanism 
with socket handles created with WPUCreateSocketHandle. A service provider should 
use WPUCompleteOverlappedRequest to announce completion of overlapped 

I/O operations that may involve a completion port. Clients may freely use operating 
system functions to create, associate, and use a completion port for completion 
notification (for example, CreateloCompletionPort, GetQueuedCompletionStatus, 
see relevant OS documentation for details). Note that completion ports are not integrated 
with the other asynchronous notification mechanisms offered by Windows Sockets 2. 
That is, a client can do a multiple-wait that includes multiple events and completion 
callbacks, but there is no predefined way for the multiple-wait to include | 
completion ports. 


Layered Service Provider Considerations 


This procedure is of particular interest to Layered Service Providers. A layered service 
provider may use this procedure, instead of WPUModifylFSHandle to create the socket 
handles it exposes to its client. The advantage of using this procedure is that all |/O 
requests involving the socket can be guaranteed to go through this service provider. 
This is true even if the client assumes that the sockets are file system handles and calls 
the file system functions ReadFile and WriteFile (although it would pay a performance 
penalty for this assumption). | 


The guarantee that all I/O goes through this layer is a requirement for layers that need 

to process the |/O stream either before or after the actual I/O operation. Creating socket 
handles using WPUCreateSocketHandle and specifying an appropriate service provider 
interface procedure dispatch table at the time of WSPStartup makes sure the layer has 
the chance to get involved in starting each I/O operation. When the client requests 
overlapped I/O operations, this service provider layer will usually have to arrange to get 
into the path of I/O completion notification as well. 


To see why this is true, consider what happens if the client associates a senpielion port 
with the socket handle for the purpose of overlapped I/O completion notification. 

The port is associated with the socket handle exposed by this layer, not the next layer’s 
socket handle. There is no way for this layer to determine if a completion port has been 
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associated or what the port is. When this layer calls the next layer’s I/O operation, it uses 
the next layer’s socket handle. The next layer’s socket handle will not have the same 
completion port association. The client’s expected completion-port notification will not 
happen without some extra help. 


The usual way a layered service provider takes care of this is to substitute a different 
overlapped I/O structure and different overlapped I/O parameters when invoking an 

I/O operation in the next layer. The substitute overlapped I/O structure references the 
Client’s stored overlapped structure and parameters. The invocation of the next layer 
sets up a callback notification. When the callback notification occurs, this layer performs 
any post-processing desired, retrieves the overlapped I/O information it stored on behalf 
of the client, discards the substitute structures, and forwards an appropriate completion 
notification to the client. 


Error Codes 
Error code — , Meaning 
WSAENOBUFS _ Not enough buffers available, too many sockets. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. | 


WPUCloseSocketHandle, WPUQuerySocketHandleContext, WPUModifyiFSHandle, 
WPUCompleteOverlappedRequest 


WPUFDIsSet 


The WPUFDIsSet function checks the membership of the specified socket handle. 


Parameters 
_ [in] Descriptor identifying the socket. 
Se ae ee es 
[in] Set to check for the membership of socket s. 
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Return Values 


If no error occurs, a value of nonzero is returned denoting that socket s is a member 
of the set. Otherwise, the return value is zero. 


WSPSelect 


WPUGetProviderPath 


The WPUGetProviderPath function retrieves the DLL path for the specified provider. 


me 


Parameters 


loProviderld 
[in] Locally unique identifier of the provider. This must be a value obtained by using 
WSCEnumProtocols. 


loszProviderDilPath 
[out] Pointer to a buffer containing a string that identifies the provider DLL’s path. 
This path is a null-terminated string and any embedded environment strings 
(such as %SystemRoot%) have not been expanded. 


lpProviderDilPathLen 
[in/out] Size of the buffer pointed to by /oszProviderDIilPath. 


loErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WPUGetProviderPath returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /oErrno. 


Remarks 


The WPUGetProviderPath function retrieves the DLL path for the specified provider. 
The DLL path is null-terminated and can contain embedded environment strings (such 
as %SystemRoot%). Thus, the string should be expanded prior to being used with 
LoadLibrary. For more information, see LoadLibrary. | 
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Error Codes 
Error code 


Meaning 


The /pProviderld does not specify a valid provider. 


WSAEINVAL 


WSAEFAULT 


Either /oszProviderDilPath or IpErrno is not in a valid part of the user 


address space, or /pProviderDilPathLen is too small. 


Windows Sockets 2.0. 


Ires 


Requi 


Version 


Header: Declared in Ws2spi.h. 


WSCinstallProvider, WSCEnumProtocols 


fylFSHandle 
The WPUMod 


WPUMod 


ied IFS handle from 


modif 


) 


ibly 


ives a (poss 


lion rece 


ifylFSHandle functi 


dll 


Parameters 


Ws2_32 


dwCatalogEntryld 


ider 


ing service prov 


the call 


ing 


ify 


tor ident 


Ip 


[in] Descr 
ProposedHandle 


[in] IFS handle allocated by the provider. 


lpErrno 


ter to the error code. 


in 


[out] Po 


Return Values 


If no error occurs, WPUModifylFSHandle returns the modified socket handle. 


it returns INVALID. SOCKET 


is available 


ic error code 


, and a specif 


Otherwise, 


loErrno. 


In 
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Remarks : 


The WPUModifyIFSHandle handle allows the Ws2_32.dll to streamline its internal 
operations by returning a possibly modified version of the supplied IFS handle. 

It is guaranteed that the returned handle is indistinguishable from the proposed handle 
as far as the operating system is concerned. IFS providers must call this function before 
returning any newly created socket descriptor to a service provider. The service provider 
will only use the modified handle for any subsequent socket operations. 

This routine is only used by IFS providers whose socket descriptors are real 

IFS handles. 


Layered Service Provider Considerations 

This procedure may also be used by a layered provider that is layered on top of a base 
IFS provider and wants to expose the base provider’s socket handles as its own instead 
of creating them with a WPUCreateSocketHandle call. A layered provider that wishes 
to “pass through” the IFS socket handles it receives from the next layer in the chain can 
call WPUModifylFSHandle, passing its own catalog entry ID as dwCatalogEntryld. This 
informs the Windows Sockets DLL that this layer, and not the next layer, should be the 
target for SPI calls involving that socket handle. | 


There are several limitations a layered provider should observe if it takes this approach. 


e The provider should expose base provider entry points for WSPSend and WSPRecv 
in the procedure dispatch table it returns at the time of WSPStartup to make sure the 
Windows Sockets SPI client’s access to these functions is as efficient as possible. 


e The provider cannot rely on its WSPSend and WSPRecv functions being invoked 


for all I/O, particularly in the case of the I/O system functions ReadFile and WriteFile. 
These functions would bypass the layered provider and invoke the base IFS 
provider's implementation directly even if the layered provider puts its own entry 
points for these functions into the procedure dispatch table. 


e The provider cannot rely on any ability to post-process overlapped I/O using 
WSPSend, WSPSendTo, WSPRecv, WSPRecvFrom, or WSPloctl. Post-processing 
notification may happen through completion ports and bypass the layered provider 
entirely. A layered provider has no way to determine that a completion port was used 
or determine what port it is. The layered provider has no way to insert itself into the 
notification sequence. 


e The provider should pass through all overlapped I/O requests directly to the base 
provider using the original overlapped parameters (for example, the 
WSAOVERLAPPED structure and completion routine pointer). The provider should 
expose the base provider entry point for WSPGetOverlappedResult. Since some 
overlapped I/O requests can bypass the layered provider completely, the layered 
provider cannot reliably mark WSAOVERLAPPED structures to determine which 
ones it can report results for, and which ones would have to be passed through to the 
underlying providers WSPGetOverlappedResult. This effectively means that 
WSPloctl has to be a pass-through operation to the underlying provider. 
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Error Codes 
Error code Meaning 
WSAEINVAL Proposed handle is invalid. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCreateSocketHandle 


WPUOpenCurrentThread 


The WPUOpenCurrentThread function opens a handle to the current thread that can 
be used with overlapped functions in a layered service provider. This is intended to be 
used by layered service providers that wish to initiate overlapped I/O from 
nonapplication threads. 


Parameters 

lpThreadld 
[out] Pointer to a WSATHREADID structure that can then be passed toe an overlapped 
function. 


loErrno 
[out] Pointer to the error code. 


Return Values 
lf no error occurs, WPUOpenCurrentThread returns the zero. ‘Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /pErrno. 


Remarks 

The WPUOpenCurrentThread funetion provides a pointer to a WSATHREADID 

structure that can then be passed to an overlapped function such as WSPSend or 
WSPRecv. Layered service providers that use a private thread in one of the upper layers 

will use WPUOpenCurrentThread to pass a WSATHREADID pointer to the lower layer 

that is administering ove lapped functions. | 
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Overlapped functions such as WSPSend and WSPRecv can then be used in the same 
way as a regular service provider. 


Every call to WPUOpenCurrentThread must have a corresponding call to 


WPUCloseThread. 

Error Codes 

Error code Meaning | 
WSANOTINITIALISED A successful WSPStartup call must occur before using this | 


function. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCloseThread, WSPSend, WSPRecv, WPUOpenCurrentThread 


WPUPostMessage - 


The WPUPostMessage function performs the standard Win32 PostMessage function in 
a way that maintains backward compatibility with older versions of Wsock32.dll. 


[in] Handle to the window that will receive the message. 


S 
[in] Message that will be posted. 
wParam | : 
[in] First parameter containing additional message-specific information. 
[Param | | | 


[in] Second parameter containing additional message-specific information. 
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Return Values 
If no error occurs, WPUPostMessage returns the vee value. Otherwise, the FALSE 
value is returned. 


anieanantesicens 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUQueryBlockingCallback 


The WPUQueryBlockingCallback function returns a pointer to a callback function the 
service provider should invoke periodically while servicing blocking operations. 


Parameters 


dwCatalogEntryld 
[in] Descriptor identifying the calling service e provider. 


lplpfnCallback 
[out] Pointer that receives the blocking callback function. 


lodwContext 
[out] Pointer that receives a context value that the service provider must pass into the 
blocking callback. 


loErrno 
[out] Pointer to the error code. 


Return Values 

lf no error occurs, WPUQueryBlockingCallback returns zero and stores a pointer toa 
blocking callback function in /pfnCallback and an associated context value in | 
lpdwContext. Otherwise, it returns SOCKET_ERROR, and a specific error code is 
available in /oErrno. 


Remarks 

The WPUQueryBlockingCallback function returns a pointer to a callback function in 
IpfnCallback to be invoked periodically during blocking operations. This function also 
returns a context value in /jodwContext to be passed into the blocking callback. 
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Under Win382, this function can return NULL in /pfnCallback, indicating that no user 
defined-blocking hook is installed. In this case, the service provider should use the 
native Win32 synchronization objects to implement blocking. 


LPBLOCKINGCALLBACK is defined as follows: 


The blocking callback will return TRUE if the service provider is to continue waiting for 
the blocking operation to complete. It will return FALSE if the blocking operation has 
been canceled with the WSPCancelBlockingCall. 


Any missing components of the address will default to a reasonable value if possible. For 
example, a missing port number will default to zero. 


Error Codes 
Error code Meaning 


WSAEFAULT _ The /pfnCallback or the |pdwContext argument is not a valid part of the 
process address space. 


WSAEINVAL — The dwCatalogEntryld is invalid. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPCancelBlockingCal 


WPUQuerySocketHandleContext 


The WPUQuerySocketHandleContext function queries the context value associated 
with the specified socket handle. 


rsnanaann 


arameters 
S 


[in] Descripton identifying the socket whose context is to be queried. 
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IoContext 
[out] Pointer that will receive the context value. 


loErrno 
[out] Pointer to the error code. 


Return Values 


lf no error occurs, WPUQuerySocketHandleContext returns zero and stores the current © 


_ context value in /oContext. Otherwise, it returns SOCKET_ERROR, and a specific error 
code is available in /oErrno. 


Remarks | 

The WPUQuerySocketHandleContext function queries the current context value 
associated with the specified socket handle. Service providers typically use this function 
to retrieve a pointer to provider-specific data associated with the socket. For example, a 
service provider can use the socket context to store a pointer to a structure containing 
the socket’s state, local and remote transport aaa e oe: and event objects for signaling 
network events. 


This function is only used by non-IFS providers since IFS providers are not able to 
supply a context value. 


Error Codes 
Error code Meaning 


WSAENOTSOCK Descriptor | is not a socket created by WPUCreateSocketHandle. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


‘WPUCreateSocketHandle 


- WPUQueueApe 


The WPUQueueApe function queues a user mode-asynchronous procedure call (APC) 
to the specified thread in order to facilitate invocation of overlapped /O Sompietion. 
routines. 


_ (continued) 
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(continued) 


Parameters 


lp Threadld | 
[in] Pointer to a WSATHREADID structure that identifies the thread context. A pointer 
to this structure is supplied to the service provider by the Ws2_32.dll as an input 
parameter to an overlapped operation. The provider should store the WSATHREADID 
structure locally and provide a pointer to this local store. The local copy of 
WSATHREADID is no longer needed once WPUQueueApc returns. 


IpfnUserApe 
[in] Points to the APC function to be called. 


dwContext © 
[in] 32-bit context value that is subsequently supplied as an input parameter to the 
APC function. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WPUQueueApc returns zero and queues the completion routine for 
the specified thread. Otherwise, it returns SOCKET_ERROR, and a specific error code is 
available in /oErrno. 


Remarks 


This function queues an APC function against the specified thread. Under Win32, this 
will be done using a user mode—asynchronous procedure call (APC). The APC will only 
execute when the specified thread is blocked in an alertable wait. For Win16, a callback 
will be made directly. In Win16 environments, this call is safe for use within an 

interrupt context. 


LPWSAUSERAPC is defined as follows: 


Because the APC mechanism supports only a single 32-bit context value, JofnUserApc 
itself cannot be the client specified—completion routine, which involves more 
parameters. The service provider must instead supply a pointer to its own APC function 
that uses the supplied dwContext value to access the needed result information for the 
overlapped operation, and then invokes the client specified—completion routine. 


For service providers where a user-mode component implements overlapped I/O, a 
typical usage of the APC mechanism is as follows. 
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1. When the I/O operation completes, the provider allocates a small buffer and packs it 
with a pointer to the client-supplied completion procedure and parameter values to 
pass to the procedure. 

2. It queues an APC, specifying the pointer to the buffer as the dwContext value and its 
own intermediate procedure as the target procedure /pfnUserApc. | 

3. When the target thread eventually enters alertable wait state, the service provider's 
intermediate procedure is called in the proper thread context. 


4. The intermediate procedure simply unpacks parameters, deallocates the buffer, and 
calls the client-supplied completion procedure. 


Error Codes | 
Error code Meaning 
WSAEFAULT  —____ The dwThreadid does not specify a valid thread. © 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSend, WSPSendTo, WSPRecv, WSPRecvFrom, WSPloct 


WPUResetEvent 


The WPUResetEvent function resets the state of the specified event object to 
nonsignaled. In Win16 environments, this call is safe for use within interrupt context. 


Parameters 
hEvent | 
[in] Handle that identifies an open event object. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, the WPUResetEvent function returns the value TRUE. Otherwise, 
FALSE is returned, and a specific error code is available in /oErrno. 
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Error Codes | 
Errorcode Meaning 
WSA_INVALID_HANDLE _ The hEventis not a valid event object handle. 


Version: Requires Windows Sockets 2.0. 
-Header: Declared in Ws2spi.h. 


WPUCreateEvent, WPUSetEvent, WPUCloseEvent 


WPUSetEvent 


The WPUSetE vent function sets the state of the specified event object to signaled. In 
Win16 environments, this call is safe for use within interrupt context. 


Parameters 
hEvent 
[in] Handle that identifies an open event object. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, the WPUSetEvent function returns the value TRUE. Otherwise, | 
FALSE is returned, and a specific error code is available in /pErrno. 


Error Codes 
Error code Meaning 
ERROR_INVALID_HANDLE The hEvent is not a valid event object handle. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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WPUCreateEvent, WPUResetEvent, WPUCloseEvent 


WSCDeinstallProvider 


The WSCDeinstallProvider function removes the specified transport provider from the 
system configuration database. 


Parameters 

loProviderld 
[in] Globally unique identifier of the provider to deinstall. This value is stored within 
each WSAPROTOCOL_INFOW structure. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSCDeinstallProvider returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /pErrno. 


Remarks | 

The WSCDeinstallProvider function removes the common Windows Sockets 2 
configuration information for the specified provider. After this routine completes 
successfully, the configuration information stored in the registry will be changed. 
However, any Ws2_32.dll instances currently in memory will not be able to see this 
change. : 


The caller of this function must remove any additional files or service provider-specific 
configuration information that | is needed to completely de-install the service provider. 


Error Codes eae 
Error code _ Meaning 
WSAEINVAL —_—__ The /pProviderld does not specify a valid provider. 


WSAEFAULT ee The /pErrno is not in a valid part of the user address space. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSClinstallProvider, WSCEnumProtocols 


WSCEnableNSProvider 


The WSCEnableNSProvider function changes the state of a given name-space 
provider. It is intended to give the end user the ability to change the state of the name- 
space providers through Control Panel. 


Parameters 


lpProviderld 
[in] Locally unique identifier for this provider. 


fEnable 
[in] Boolean value that, if TRUE, the provider is set to the active state. If FALSE, the 
provider is disabled and will not be available for query operations or 
service registration. 


Return Values 

If no error occurs, the WSCEnableNSProvider function returns NO_ERROR (zero). 
Otherwise, it returns SOCKET_ERROR and must set the appropriate error code using 
SetLastError. 


Remarks 


The name space configuration functions do not affect applications that are already 
running. Newly installed name-space providers will not be visible to applications nor will 
the changes in a name-space provider’s activation state. Applications launched after the 
call to WSCEnableNSProvider will see the changes. 


The WSCEnableNSProvider function is intended to be used by the Control Panel to 
change the state of the providers. An ISV should not just blindly de-activate another 
ISV’s provider in order to activate its own. The choice should be left to the user. 
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Error Codes 
Error code Meaning 
WSAEINVAL The specified name-space—provider identifier is invalid. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSCEnumProtocols 


The WSCEnumProtocols function retrieves information about available transport 
protocols. 


Parameters 


IpiProtocols | 
[in] Null-terminated array of /Protoco/ values. This parameter is optional; if /oi/Protocols 
is NULL, information on all available protocols is returned. Otherwise, information is 
retrieved only for those protocols listed in the array. 


IpProtocolBuffer 
out] Buffer that is filled with WSAPROTOCOL_INFOW structures. 


wBufferLength 

in/out] On input, the count of bytes in the /pProtoco/Buffer buffer passed to 
WSCEnumProtocols. On output, the minimum buffer size that can be passed to 
WSCEnumProtocols to retrieve all the requested information. 


IpErrno— 
out] Pointer to the error code. 


Return Values 


If no error occurs, WSCEnumProtocols returns the number of protocols to be reported 
on. Otherwise, a value of SOCKET_ERROR is returned and a specific error code is 
available in /pErrno. 
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Remarks 


This function is used to discover information about the collection of transport protocols 
installed on the local machine. This function differs from its API counterpart 
(WSAEnumProtocols) in that WSAPROTOCOL_INFOW structures for all installed 
protocols, including layered protocols, can be obtained. (WSAEnumProtocols only 
returns information on base protocols and protocol chains.) The /piProtocols parameter 
can be used as a filter to constrain the amount of information provided. Typically, a 


_ NULL pointer is supplied so the function will return information on all available 


transport protocols. 


A WSAPROTOCOL_INFOW structure is provided in the buffer pointed to by 
lpProtocolBuffer for each requested protocol. If the supplied buffer is not large enough 
(as indicated by the input value of |jpdwBufferLength ), the value pointed to by _ 
lodwBufferLength will be updated to indicate the required buffer size. The Windows 
Sockets SPI client should then obtain a large enough buffer and call this function again. 
The WSCEnumProtocols function cannot enumerate over multiple calls; the passed-in 
buffer must be large enough to hold all expected entries in order for the function to 
succeed. This reduces the complexity of the function and should not pose a problem 
because the number of protocols loaded on a machine is typically small. 


The order in which the WSAPROTOCOL_INFOW structures appear in the buffer 
coincides with the order in which the protocol entries were registered by the service 
provider with the Ws2_32.dll, or with any subsequent reordering that may have occurred 
through the Windows Sockets applet supplied for establishing default 

transport providers. 


Error Codes 
Error code Meaning 


WSAEFAULT One of more of the arguments is not in a valid part of the user 
address space. 

WSAEINVAL Indicates that one of the specified parameters was invalid. 

WSAENOBUFS _ Buffer length was too small to receive all the relevant 
WSAPROTOCOL_INFOW structures and associated information. 
Pass in a buffer at least as large as the value returned 
in jodwBufferLength. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 
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WSCGetProviderPath 


The WSCGetProviderPath function retrieves the DLL path for the specified provider. 


Parameters 


lpProviderld 
[in] Locally unique identifier of the provider. This value is obtained by using 
WSCEnumProtocols. 

_ IoszProviderDllPath 

_ [out] Pointer to a buffer into which the provider DLL’s path string is returned. The pal 
is a null-terminated string and any embedded environment strings, such 
as %SystemRoot%, have not been expanded. 

loProviderDilPathLen " 
[in/out] Size of the buffer pointed to by the ipszProviderDiirain parameter. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSCGetProviderPath returns zero. Otherwise, it returns © 
SOCKET_ERROR. The specific error code is available in /joErrno. 


Remarks 

~The WSCGetProviderPath function retrieves the DLL path for the specified srovider 

The DLL path can contain embedded environment strings, such as %SystemRoot%, and > 
thus should be expanded prior to being used with the Win32 ee ee function. 

For more information, see LoadLibrary. 


Error Codes | 
Error code _ Meaning | | 
WSAEINVAL _ The |pProviderld parameter does not specify a valid provider. 
WSAEFAU LT The /pszProviderDilPath or IpErrno parameter is not in a valid part 


of the user address space, or IpProviderDilPathLen is too small. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSClinstallProvider, WSCEnumProtocols 


WSClnstallNameSpace 


The WSClinstallNameSpace function installs a name-space provider. For providers that 
are able to support multiple names spaces, this function must be called once for ever 
name space supported, and a unique provider identifier must be supplied each time. 


Parameters 


szidentifier 
[in] Pointer to a string that identifies the provider for use in the GUID. 


szPathName 
[in] Pointer to a string that contains the path to the provider's DLL image. The strin 


observes the usual rules for path resolution: this path can contain embedded 
environment strings (such as %SystemRoot%). Such environment strings are 
expanded whenever the Ws2_32.dll needs to subsequently load the provider DLL 
on behalf of an application. After any embedded environment strings are expanded, 
the Ws2_32.dll passes the resulting string into the LoadLibrary function to load the 
provider into memory. For more information, see LoadLibrary. 


dwNameSpace 
[in] Descriptor that specifies the name space supported by this provider. 


dwVersion 7 . ay 
in] Descriptor that specifies the version number of the provider. 


IpProviderld 7 
in] Unique identifier for this provider. This GUID should be generated 


by Uuidgen.exe. | 7 
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Return Values 


If no error occurs, the WSCInstallNameSpace function returns NO_ERROR (zero). 
Otherwise, it returns SOCKET_ERROR if the function fails, and it must set the 
appropriate error code using SetLastError. 


Remarks 


The name space configuration functions do not affect applications that are already 
running. Newly installed name-space providers will not be visible to applications nor will 
the changes in a name-space provider's activation state. Applications launched after the 
call to WSCInstallNameSpace will see the changes. 


Error Codes 
Error code Meaning 
WSAEACCESS Calling routine does not have sufficient privileges to install 


a name space. ; 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSClinstallProvider 


The WSClnstallProvider function installs the specified transport provider into the 
system configuration database. 


Parameters 


|pProviderld | = 
[in] Pointer to a provider-selected, globally unique identifier (GUID). 


lpszProviderDilPath Pos ee ag oe 
[in] Pointer to a string containing the load path to the provider's DLL. This string 
observes the usual rules for path resolution and can contain embedded environment 
strings (such as %SystemRoot%). Such environment strings are expanded whenever 
the Ws2_32.dll needs to subsequently load the provider DLL on behalf of an 
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application. After any embedded environment strings are expanded, the Ws2_32.dll 
passes the resulting string into the LoadLibrary function to load the provider into 
memory. For more information, see LoadLibrary. 


IpProtocolinfoList 
[in] Points to an array of WSAPROTOCOL._ INFOW structures. Each structure defines 
a protocol, address_family, and socket_type supported by the provider. 


dwNumberOfEntries 
[in] Contains the number of entries in the ipProtocolinfoList array. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSCinstallProvider returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in /pErrno. 


Remarks 


This routine creates the necessary common Windows Sockets 2 configuration 
information for the specified provider. It is applicable to base protocols, layered 
protocols, and protocol chains. After this routine completes successfully, the protocol — 
information provided in /pProtocolinfoList will be returned by the WSAEnumProtocols. 
Note that in Win32 environments, only instances of the Ws2_32.dll created after 

a successful completion of this function will include the new entries in 
WSAEnumProtocols. 


Any file installation or service provider-specific configuration must be performed by the 


caller. 

Error Codes 

Error code Meaning 

WSAEFAULT | One or more of the arguments is not in a valid part of the user 


address space. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSCDeinstallProvider, WSCEnumProtocols 
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WSCUnInstallNameSpace 


The WSCUnInstaliNameSpace function uninstalls the indicated name-space provider. 


Parameters 


loProviderld 
[in] Unique identifier for this provider. 


Return Values 


If no error occurs, WSCUnInstallNameSpace returns NO_ERROR (zero). Otherwise, it | 
returns SOCKET_ERROR and must set the appropriate error code using SetLastError. 


Remarks 


The name space configuration functions do not affect applications that are already 
running. Newly installed name-space providers will not be visible to applications nor will 
the changes in a name-space provider's activation state. Applications launched after the 
call to WSCUnInstallNameSpace will see the changes. 


Error Codes 
Error code Meaning 
WSAEINVAL Specified name-space—provider identifier is invalid. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
Library: Use Ws2_32.lib. 


WSCWriteProviderOrder 
The WSCWriteProviderOrder function is used to reorder the available transport 


providers. The order of the protocols determines the pronty ofa protocol when being 
enumerated or selected for us. 
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Parameters 


lpwdCatalogEntryld 
[in] Array of CatalogEntryld elements found in the WSAPROTOCOL_INFO structure. 
The order of the CatalogEntryld elements is the new priority ordering for 
the protocols. 


dwNumberOfEntries 
[in] Number of elements in the /owdCatalogEntryld array. 


Return Values 


The function returns ERROR_SUCCESS (zero) if the routine is successful. Otherwise, it 
returns a specific error code. 


Remarks 


The order in which transport service providers are initially installed governs the order in 
which they are enumerated through WSCEnumProtocols at the service provider 
interface, or through WSAEnumProtocols at the application interface. More importantly, 
this order also governs the order in which protocols and service providers are considered 
when a client requests creation of a socket based on its address family, type, and 
protocol identifier. | 


Windows Sockets 2 includes an application called Sporder.exe that allows the catalog of 
installed protocols to be reordered interactively after protocols have already been 
installed. Windows Sockets 2 also includes an auxiliary DLL, Sporder.dll that exports this 


_ procedural interface for reordering protocols. This interface can be imported by linking 


with Sporder.lib. 

Here are scenarios in which the WSCWriteProviderOrder function can fail. 

e The dwNumberOfEntries parameter is not equal to the number of registered service 
providers. 

e The lpwdCatalogEntryld contains an invalid catalog identifier. 

e The |owdCatalogEntryld does not contain all valid catalog identifiers exactly one time. 


e The routine is not able to access the registry for some reason (for example, 
inadequate user permissions). 


e Another process (or thread) is currently calling the function. 


Error Codes 

Error code Meaning | 

WSAEINVAL Input parameters were bad, no action was taken. 
ERROR_BUSY Routine is being called by another thread or process. 


~ (other) Routine may return any registry error code. 
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ersion: Requires Windows Sockets 2.0. 
Header: Declared in Sporder.h. 
Library: Included as a resource in Sporder.dll. 


WSPAccept 


The WSPAccept function conditionally accepts a connection based on the return value 
of a condition function. 


Parameters 
S 


[in] Descriptor identifying a socket that is listening for connections after a WSPListen. 


addr 
[out] Optional pointer to a buffer that receives the address of the connecting entity, as 
known to the service provider. The exact format of the addr argument is determined 
by the address family established when the socket was created. 


addrlen 
[in/out] Optional pointer to an integer that contains the length of the addr parameter. 


Ipt_nCondition 
[in] Procedure instance address of an optional-condition function furnished by 
Windows Sockets. This function is used in the accept or reject decision based on the 
caller information passed in as parameters. 


dwCallbackData 
[in] Callback data to be passed back to the Windows Socket 2 client as the value of 
the dwCallbackData parameter of the condition function. This parameter is not 
interpreted by the service provider. — 


lpErrno : 
out] Pointer to the error code. 
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Return Values 


If no error occurs, WSPAccept returns a value of type SOCKET that is a descriptor for 
the accepted socket. Otherwise, a value of INVALID_SOCKET is returned, and a 
specific error code is available in /oErrno. 


~ Remarks © 


The WSPAccept function extracts the first connection on the queue of pending 
connections on socket s, and checks it against the condition function, provided the 
condition function is specified (that is, not NULL). The condition function must be 
executed in the same thread as this routine. If the condition function returns 
CF_ACCEPT, WSPAccept creates a new socket. 


Newly created sockets have the same properties as the socket s, including network 
events registered with WSPAsyncSelect or with WSPEventSelect. As described in 
Descriptor Allocation, when new socket descriptors are allocated, IFS providers must call 
WPUModifylFSHandle and non-IFS providers must call WPUCreateSocketHandle. 


If the condition function returns CF_REJECT, WSPAccept rejects the connection 
request. If the application’s accept/reject decision cannot be made immediately, the 
condition function will return CF_DEFER to indicate that no decision has been made. No 
action about this connection request is to be taken by the service provider. When the 
application is ready to take action on the connection request, it will invoke WSPAccept 
again and return either CF_ACCEPT or CF_REJECT as a return value from the 
condition function. | 


For sockets that are in the (default) blocking mode, if no pending connections are 
present on the queue, WSPAccept blocks the caller until a connection is present. For — 
sockets in nonblocking mode, if this function is called when no pending connections are 
present on the queue, WSPAccept returns the error code WSAEWOULDBLOCK. The 
accepted socket cannot be used to accept more connections. ne Original socket 
remains open. 


The argument adar is a result parameter that is filled with the address of the connecting 
entity, as known to the service provider. The exact format of the addr parameter is 
determined by the address family in which the communication is occurring. The addrlen 
is a value-result parameter; it will initially contain the amount of space pointed to by adr. 
On return, it must contain the actual length (in bytes) of the address returned by the 
service provider. This call is used with connection-oriented socket types such as 
SOCK_STREAM. If addr and/or adadrlen are equal to NULL, then no information about - 
the remote address of the accepted socket is returned. Otherwise, these two parameters 
shall be filled in regardless of whether the condition function is specified or 

what it returns. : : 


The prototype of the condition function is as follows. 
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The /pCallerld and |pCallerData are value parameters that must contain the address of 
the connecting entity and any user data that was sent along with the connection request. 
If no caller identifier or caller data is available, the corresponding parameter will be 
NULL. Many network protocols do not support connect-time caller data. Most 
conventional network protocols can be expected to support caller identifier information at 
connection-request time. The buf part of the WSABUF pointed to by /pCallerid points to 
a SOCKADDR. The SOCKADDR is interpreted according to its address family (typically 
by casting the SOCKADDR to some type specific to the address family). 


The /pSQOS parameter references the flow specifications for socket s specified by the 
caller, one for each direction, followed by any additional provider-specific parameters. 
The sending or receiving flow specification values will be ignored as appropriate for any 
unidirectional sockets. A NULL value for /oSQOS indicates that there is no caller- 
supplied QOS and that no negotiation is possible. A non-NULL /pSQOS pointer indicates 
that a QOS negotiation is to occur or that the provider is prepared to accept the QOS 
request without negotiation. 


The /pCalleeld is a value parameter that contains the local address of the connected 
entity. The buf part of the WSABUF pointed to by /pCallee/d points to a SOCKADDR. 
The SOCKADDR is interpreted according to its address family (typically by casting the 
SOCKADDR to some type specific to the address family). | 


The /pCalleeData is a result parameter used by the condition function to supply user 
data back to the connecting entity. The storage for this data must be provided by the 
service provider. The /pCalleeData->l/en initially contains the length of the buffer 
allocated by the service provider and pointed to by /pCalleeData->buf. A value of zero” 
means passing user data back to the caller is not supported. The condition function will 
copy up to /pCalleeData->len bytes of data into |oCalleeData->buf, and then update 
IpCalleeData->len to indicate the actual number of bytes transferred. If no user data is to 
be passed back to the caller, the condition function will set /pCalleeData->len to zero. 
The format of all address and user data is specific to the address family to which the 
socket belongs. | . | 


The dwCallbackData parameter value passed to the condition function is the value 
passed as the dwCallbackData parameter in the original WSPAccept call. This value is 
interpreted only by the Windows Sockets 2 client. This allows a client to pass some 
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context information from the WSPAccept call site through to the condition function, 
which provides the condition function with any additional information required to 
determine whether to accept the connection. A typical usage is to pass a (suitably cast) 
pointer to a data structure containing references to app lealiony -defined objects with 
which this socket is associated. 


Error Codes 
Error code 


WSAECONNREFUSED 


WSAENETDOWN 
WSAEFAULT 


WSAEINTR 


WSAEINPROGRESS 
WSAEINVAL 


WSAEMFILE 


WSAENOBUFS 
WSAENOTSOCK 
WSAEOPNOTSUPP 


WSATRY_AGAIN 


WSAEWOULDBLOCK 


WSAEACCES 


Meaning 

Connection request was forcefully rejected as indicated in the 
return value of the condition function (CF_REJECT). 

Network subsystem has failed. 

The adadrlen argument is too small or the /pfnCondition is not 
part of the user address space. 


(Blocking) call was canceled through 
WSPCancelBlockingCall. 


Blocking Windows Sockets call is in progress. 


WSPListen was not invoked prior to WSPAccept, parameter 
g specified in the condition function is not a valid value, the 
return value of the condition function is not a valid one, or any 
case where the specified socket is in an invalid state. 


Queue is nonempty upon entry to WSPAccept and there are 
no socket descriptors available. | 


No buffer space is available. 
Descriptor is not a socket. 


Referenced socket is not a type that supports connection- 
oriented service. 


Acceptance of the connection request was deferred as 
indicated in the return value of the condition function 
(CF_DEFER). 


Socket is marked as nonblocking and no panna are 
present to be accepted. 


Connection request that was offered has timed out or been 
withdrawn. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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WSPAccept, WSPBind, WSPConnect, WSPGetSockOpt, WSPListen, WSPSelect, 
WSPSocket, WSPAsyncSelect, WSPEventSelect 


WSPAddressToString 


The WSPAddressToString function converts all components of a SOCKADDR 
structure into a human readable-numeric string representation of the address. This is 
used mainly for display purposes. 


Parameters 


IpsaAddress | 
[in] Points to a SOCKADDR structure to translate into a string. 


dwAdaressLength 
in] Length of the address SOCKADDR. 


lpProtocolinto 
[in] (required) WSAPROTOCOL_INFO structure associated with the provider that will 


o the translation. 


lpszAddressString 
out] Buffer that receives the human readable—address string. 


lpdwAddressStringLength 
in/out] Length of the AddressString buffer. Returns the length of the string actually 
copied into the buffer. If the supplied buffer is not large enough, the function fails with 
a specific error of WSAEFAULT and this parameter is updated with the required size 
in bytes. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPAddressToString returns zero. Otherwise, it returns 
SOCKET_ERROR, and a specific error code is available in pErrno. 
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Layered Service Provider Considerations 


A layered service provider supplies an implementation of this function, but it is also a 
client of this function if and when it calls WSPAddressToString of the next layer in the 
protocol chain. Some special considerations apply to the /oProtocollnfo parameter as itis 
propagated down through the layers of the protocol chain. 


If the next layer in the protocol chain is another layer, then, when the next layer’s — 
WSPAddressToString is called, this layer must pass to the next layer a /pProtocolinfo 
parameter that references the same unmodified WSAPROTOCOL_INFO structure with 
the same unmodified chain information. However, if the next layer is the base protocol 
(that is, the last element in the chain), this layer performs a substitution when calling the 
base providers WSPAddressToString. In this case, the base provider's _ 
WSAPROTOCOL_INFO structure should be referenced by the /pProtocollnfo parameter. 
One vital benefit of this policy is that base service providers do not have to be aware of 
protocol chains. 


This same propagation policy applies when propagating a WSAPROTOCOL_INFO 
structure through a layered sequence of other functions such as WSPDuplicateSocket, 
WSPStartup, WSPSocket, or WSPStringToAddress. 


Error Codes 
Error code Meaning 


WSAEFAULT Specified AddressString buffer is too small. Pass in a larger buffer. 


WSA_EINVAL = Specified Address is not a valid socket address, or its address family 
is not supported by the provider, or the specified /pProtocolinfo did not 
refer to a WSAPROTOCOL_INFO siructure supported by the 
provider. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPAsyncSelect 


The WSPAsyncSelect function requests Windows message-based event notification of 
network events for a socket. 


Parameters 
S 


hWnd 
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[in] Descriptor identifying the socket for which event ‘hotification is required. 


[in] Handle identifying the window that should receive a message when a network 


event occurs. 
wMsg 


[in] Message to be sent when a network event occurs. 


lEvent 


[in] Bitmask that specifies a combination of network events in which the Windows 
Sockets SPI client is interested. 


loErrno 


[out] Pointer to the error code. 


This function is used to request that the service provider send a Windows message to 
the client's window hWnd whenever it detects any of the network events specified by the 
[Event parameter. The service provider should use the WPUPostMessage function to 
post the message. The message to be sent is specified by the wMsg parameter. The 
socket for which notification is required is identified by s. 


This function automatically sets socket s to nonblocking mode, regardless of the value of 
[Event. See WSPloct! about how to set the socket back to blocking mode. 


The /Event parameter is constructed by using the bitwise OR operator with any of the 
values specified in the ioronng table. 


~ Value 


FD_READ 
FD_WRITE 
FD_OOB 
FD_ACCEPT 
FD_CONNECT 
FD CLOSE | 
FD_QOS 
FD_GROUP_QOS 
FD_ROUTING_ 


INTERFACE_CHANGE 


FD ADDRESS 
LIST_CHANGE — 


Meaning 


Issues notification of readinéss for reading. 
Issues notification of readiness for writing. 
Issues notification of the arrival of OOB data. 


Issues notification of incoming connections. 
Issues notification of completed connections. 


Issues. notification of socket closure. 
Issues notification of socket (O°) changes. 
Reserved. 


_ Issues notification of routing interface change for the 
specified destination. 


~ Issues notification of local address list change for the 


socket’s protocol family. 
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Invoking WSPAsyncSelect for a socket cancels any previous WSPAsyncSelect or 
WSPEventSelect for the same socket. For example, to receive notification for both 
reading and writing, the Windows Sockets SPI client must call WSPAsyncSelect with 
both FD_READ and FD_WRITE, as follows: 


It is not possible to specify different messages for different events. The following code 
will not work; the second call will cancel the effects of the first, and only FD_WRITE 
events will be reported with message wMsg2: 


To cancel all notification (for example, to indicate that the service provider should send 
no further messages related to network events on the socket) /Event will be set to zero: 


Since a socket created by WSPAccept has the same properties as the listening socket 
used to accept it, any WSPAsyncSelect events set for the listening socket apply to the 
accepted socket. For example, if a listening socket has WSPAsyncSelect events 
FD_ACCEPT, FD_READ and FD_WRITE, then any socket accepted on that listening 
socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same 
wMsg value used for messages. If a different wMsg or events are needed, the Windows 
Sockets SPI client must call WSPAsyncSelect, passing the accepted socket and the 
new information. 


When one of the nominated network events occurs on the specified socket s, the service 
provider uses WPUPostMessage to send message wMsg to the Windows Sockets SPI 
client's window hWnd. The wParam argument identifies the socket on which a network 
event has occurred. The low word of /Param specifies the network event that has 
occurred. The high word of /Param contains any error code. The error code can be any 


error as defined in Ws2spi.h. 


The possible network event codes that may be indicated are shown in the following 
table. : 7 


Value Meaning 

FD_READ Socket s ready for reading. 

FD_WRITE Socket s ready for writing. 

FD_OOB OOB data ready for reading on socket s. | 
FD_ACCEPT Socket s ready for accepting a new incoming connection. 
FD_CONNECT Connection initiated on socket s completed. 

FD_CLOSE Connection identified by socket s has been closed. 


FD_QOS QOS associated with socket s has changed. 
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Value Meaning 

FD_GROUP_QOS Reserved. | 
FD_ROUTING_ Local interface that should be used to send to the specified 
INTERFACE_CHANGE _ destination has changed. 

FD_ADDRESS_ List of addresses of the socket’s protocol family to which the 


LIST_CHANGE Windows Socket SPI client can bind has changed. 


Return Values 

The return value is zero if the Windows Sockets SPI client’s declaration of interest in the 
network event set was successful. Otherwise, the value SOCKET _ERROR is returned, 
and a specific error code is available in /pErrno. | 


| Remarks 


Although WSPAsyncSelect can be called with interest in multiple events, the service 
provider issues the same Windows message for each event. 


A Windows Sockets 2 provider will not continually flood a Windows Sockets SPI client 
with messages for a particular network event. Having successfully posted notification of © 
a particular event to a Windows Sockets SPI client window, no further message(s) for 
that network event will be posted to the window until the Windows Sockets SPI client 
makes the function call that implicitly reenables notification of that network event. 


Event Re-enabling function 

FD_READ WSPRecv or WSPRecvFrom 

FD_WRITE WSPSend or WSPSendTo 

FD_OOB WSPRecv or WSPRecvFrom | 
FD_ACCEPT WSPAccept unless the error code returned is 


WSATRY_AGAIN indicating that the condition function 
returned CF_DEFER 


FD_CONNECT None 

FD_CLOSE — None 

FD_QOS WSPloctl with SIO_GET_QOS 

FD_GROUP_QOS Reserved. | 

FD_ROUTING_ | WSPloctl with command 

INTERFACE_CHANGE SIO_ROUTING_INTERFACE_CHANGE _ 
FD_ADDRESS_ — WSPloctl with nee ie waa er aa a 
LIST_ CHANGE : 7 | 


Any call to the reenabliad routine, even one that fails, results | in reenabiing of message 
posting ol the relevant event. : 
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For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is level-triggered. 
This means if the reenabling routine is called and the relevant condition is still met after 
the call, a WSPAsyncSelect message is posted to the Windows Sockets SPI client. 


The FD_QOS event is considered edge triggered. A message will be posted exactly 
once when a QOS change occurs. Further messages will not be forthcoming until either 
the provider detects a further change in quality of service or the Windows Sockets SPI 
client renegotiates the quality of service for the socket. 


The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events 
are considered edge triggered as well. A message will be posted exactly once when a 

_ change occurs after the Windows Socket 2 SPI client has requested the notification by 

issuing WSPloctl with SIO_LROUTING_INTERFACE_CHANGE or 

SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be 

forthcoming until the SPI client reissues the IOCTL and another change is detected since 

the IOCTL has been issued. 


lf any event has already occurred when the Windows Sockets SPI client calls 
WSPAsyncSelect or when the reenabling function is called, then an appropriate 
message is posted. For example, consider the following sequence: 


@ An SPI client calls WSPListen. 
e Aconnect request is received but not yet accepted. 


e The Windows Sockets SPI client calls WSPAsyncSelect specifying that it wants to 
receive FD_ACCEPT messages for the socket. 


Due to the persistence of events, the Windows Sockets service provider posts an 
FD_ACCEPT message immediately. 


The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted 
when a socket is first connected with WSPConnect (after FD_CONNECT, if also 
registered) or accepted with WSPAccept, and then after a WSPSend or WSPSendTo 
fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, a 
Windows Sockets SPI client can assume that sends are possible starting from the first 
FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such 
a failure the Windows Sockets SPI client will be notified that sends are again possible 
with an FD_WRITE message. . 


The FD_OOB event is used only when a socket is configured to receive OOB data 
separately. If the socket is configured to receive OOB data inline, the OOB (expedited) 
data is treated as normal data and the Windows Sockets SPI client must register an 
interest in FD_READ events, not FD_OOB events. | 


The error code in an FD_CLOSE message indicates whether the socket close was 
graceful or abortive. If the error code is zero, then the close was graceful; if the error 
code is WSAECONNRESET, then the socket’s virtual circuit was reset. This monly applies 
to connection-oriented sockets such as SOCK _ STREAM. 
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The FD_CLOSE message is posted when a close indication is received for the virtual 
circuit corresponding to the socket. In TCP terms, this means the FD_CLOSE is posted 
when the connection goes into the TIME WAIT or CLOSE WAIT states. This results from 
the remote end performing a WSPShutdown on the send side or a WSPCloseSocket. 
FD_CLOSE shall only be posted after all data is read from a socket. 


In the case of a graceful close, the service provider should only send an FD_CLOSE 
message to indicate virtual circuit closure after all the received data has been read. It 
should not send an FD_READ message to indicate this condition. 


The FD_QOS message is posted when any member in the flow specification associated 
with socket s has changed, respectively. The service provider must update the QOS 
information available to the client through WSPloctl with SIO_GET_QOS. 


The FD_ROUTING_INTERFACE_CHANGE message is posted when the local interface 
that should be used to reach the destination specified in WSPloctl with 
SIO_ROUTING_INTERFACE_CHANGE changes after such IOCTL has been issued. 


The FD_ADDRESS_LIST_CHANGE message is posted when the list of addresses to 
which the Windows Socket 2 SPI client can bind changes after WSPloctl with 
SIO_ADDRESS_ LIST_CHANGE has been issued. 


Here is a summary of events and conditions for each asynchronous notification 
message: 
e FD_READ: 
_ @ When WSPAsyncSelect i is called, if there i is data currently available to receive. 
e When data arrives, if FD_READ is not already posted. 


e After WSPRecv or WSPRecvfrom is called (with or without MSG_PEEK), if data is 
still available to receive. 


Note When WSPSetSockOpt SO_OOBINLINE is enabled, data includes both 
normal data and OOB data in the instances noted in the preceding. 


° FD _WRITE: 
e When WSPAsyncSelect i is called, if a WSPSend or WSPSendTo is possible. 
e After WSPConnect or WSPAccept is called, when connection is established. 


_e After WSPSend or WSPSendTo fails with WSAEWOULDBLOCK, when WSPSend 
or WSPSendTo is likely to succeed. 


e After WSPBind on a datagram socket. FD_WRITE may or may not occur at this 
time (implementation dependent). In any case, a connectionless socket is always — 
. writeable immediately after WSPBind. 
e FD_OOB: Only valid when WSPSetSockOpt SO _OOBINLINE i is disabled (default). 
@ When WSPAsyncSelect i is called, if there is OOB data currently available to 
receive with the MSG_OOB flag. 


-@ When OOB data arrives, if FD_OOB is not already posted. 
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e After WSPRecv or WSPRecvfrom is called with or without MSG _OOB flag, if OOB 
data is still available to receive. 
e FD_ACCEPT: 
| e When WSPAsyncSelect is called, if there is currently a connection request 
available to accept. 
e When a connection request arrives, if FD_ACCEPT is not already posted. 
e After WSPAccept is called, if there is another connection request available 
to accept. 
e FD_CONNECT: 
e When WSPAsyncSelect is called, if there is currently a connection established. 
e After WSPConnect is called, when connection is established (even when 
WSPConnect succeeds immediately, as is typical with a datagram socket, and 
even when it fails immediately). 
e After WSAJoinLeaf is called, when the j join operation sonnets 
e After connect, WSAConnect, or WSAJoinLeaf was called with a nonblocking, 
connection-oriented socket. The initial operation returned with a specific error of 
WSAEWOULDBLOCK, but the network operation went ahead. Whether the 
operation eventually succeeds or not, when the outcome has been determined, 


FD_CONNECT happens. The client should check the error code to determine 
whether the outcome was a success or failure. 


e FD_CLOSE: Only valid on connection-oriented sockets (for example, 
SOCK_STREAM): 


e When WSPAsyncSelect is called, if socket connection has been closed. 


e After the remote system initiated a graceful close, when no data is currently 
available to receive (if data has been received and is waiting to be read when the 
remote system initiates a graceful close, the FD_CLOSE is not delivered until all 
pending data has been read). 


e After the local system initiates a graceful close with WSPShutdown and the 
remote system has responded with End of Data notification (for example, TCP 
FIN), when no data is currently available to receive. 


° When the remote system terminates connection (for example, sent TCP RST), and 
[Param will contain the WSAECONNRESET error value. 


Note FD_CLOSE is not posted after WSPClosesocket is called. 


e FD_QOS: 


e When WSPAsyncSelect i Is called, if the hee associated with the socket has 
been changed, | 


e After WSPloctl with SIO_ GET _QOS is called, when the Q0S i is changed. 
e FD_GROUP_QOS: Reserved. 
e FD_ROUTING_INTERFACE_CHANGE: 
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e After WSPloctl with SIO_ROUTING_INTERFACE_CHANGE is called, when the 
local interface that should be used to reach the destination specified in the 


lIOCTL changes. 


e FD_ADDRESS_LIST_ 


CHANGE: 


e After WSPloctl with SIO_ADDRESS_LIST_CHANGE is called, when the list of 
local addresses to which the Windows Socket 2 SPI client can bind changes. 


Error Codes 
Error code 


WSAENETDOWN 
WSAEINVAL 


~ WSAEINPROGRESS 


WSAENOTSOCK 


Meaning 


Network subsystem has failed. 


Indicates that one of the specified parameters was invalid such 
as the window handle not referring to an existing window, or 
the specified socket is in an invalid state. 

Blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. 


Descriptor is not a socket. 


Additional error codes can be set when the service provider issues a message to a 
Windows Sockets SPI client’s window. This error code is embedded in the IParam 
member of the message. Possible error codes for each network event are as shown in 


the following tables. 
Event: FD_CONNECT 
Error code | 


WSAEAFNOSUPPORT 


WSAECONNREFUSED 
WSAENETUNREACH 
WSAEFAULT 
WSAEINVAL 
WSAEISCONN 
WSAEMFILE | 
WSAENOBUFS 


WSAENOTCONN 
WSAETIMEDOUT 


Meaning 

Addresses in the specified family cannot be used with this 
socket. 

Attempt to connect was forcefully rejected. 

Network cannot be reached from this host at this time. 
The namelen argument is incorrect. | 

Socket is already bound to an address. 

Socket is already connected. 

No more file descriptors are available. 


No buffer space is available. The socket cannot be 
connected. 


Socket is not connected. 


Attempt to connect timed out without establishing a 
connection. 
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Event: FD_CLOSE 


Error code Meaning 

WSAENETDOWN | Network subsystem has failed. 

WSAECONNRESET - Connection was reset by the remote side. 

WSAECONNABORTED _ Connection was terminated due to a time-out or other 
failure. 


Event: FD_READ 
Event: FD_WRITE 

Event: FD_OOB 

Event: FD_ACCEPT 

Event: FD_QOS 

Event: FD_GROUP_QOS 

Event: FD_ADDRESS_LIST_CHANGE 


_ Error code Meaning 


WSAENETDOWN Network subsystem has failed. 


Event: FD_ROUTING_INTERFACE_CHANGE 


Error code Meaning 
WSAENETUNREACH Specified destination can no longer be reached. 
WSAENETDOWN Network subsystem has failed. 


EEE 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSelect 


WSPBind 


The WSPBind function associates a local address (that is, name) with a socket. 
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Parameters 
[in] Descriptor identifying an unbound socket. 


name 
[in] Address to assign to the socket. The SOCKADDR structure is defined as follows: 


Except for the sa_family member, SOCKADDR contents are expressed in network 
byte order. In Windows Sockets 2, the name parameter is not strictly interpreted as a 
pointer to a SOCKADDR structure. It is cast this way for Windows Sockets _ 
compatibility. The actual structure is interpreted differently in the context of different. 
address families. The only requirements are that the first u_short is the address family 
and the total size of the memory buffer in bytes is namelen. 


namelen 
[in] Length of the name. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPBind returns zero. Otherwise, it returns SOCKET __ ERROR, and 
a specific error code is available in /oErrno. 


Remarks 

This routine is used on an unconnected connectionless or connection-oriented socket, 
before subsequent calls to WSPConnect or WSPListen. When a socket is created with. 
WSPSocket, it exists in a name space (address family), but it has no name or local 
address assigned. WSPBind establishes the local association of the socket by assigning 
a local name to an unnamed socket. 


Asan example, in the Internet address family, a name consists of three parts: the 
address family, a host address, and a port number that identifies the Windows Sockets 
SPI client. In Windows Sockets 2, the name parameter is not strictly interpreted asa 
pointer to a SOCKADDR structure. Service providers are free to regard it as a pointer to 
a block of memory of size namelen. The first two bytes in this block (corresponding to 
sa_family in the SOCKADDR declaration) must contain the address family that was 
used to create the socket. Otherwise, the error WSAEFAULT will be indicated. — 
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lf a Windows Sockets 2 SPI client does not care what local address is assigned to it, it 
will specify the manifest constant value ADDR_ANY for the sa_data member of the 
name parameter. This instructs the service provider to use any appropriate network 
address. For TCP/IP, if the port is specified as zero, the service provider will assign a 
unique port to the Windows Sockets SPI client with a value between 1024 and 5000. 
The SPI client can use WSPGetSockName after WSPBind to learn the address and the 
port that has been assigned to it. However, note that if the Internet address is equal to 
INADDR_ANY, WSPGetSockOpt will not necessarily be able to supply the address until 
the socket is connected, since several addresses can be valid if the host is multihomed. 


Error Codes 
Error code 


WSAENETDOWN 
WSAEADDRINUSE 


WSAEADDRNOTAVAIL 
WSAEFAULT 


WSAEINPROGRESS 
WSAEINVAL 
WSAENOBUFS 
WSAENOTSOCK 


Meaning 


Network subsystem has failed. 


Some process on the machine has already bound to the same fully- 
qualified address (for example, IP address and port in the af_inet 
case) and the socket has not been marked to allow address reuse 
with SO_REUSEADDR. (See the SO_REUSEADDR socket option 
under WSPSetSockOpt.) 


Specified address is not a valid address for this machine. 


Name or the namelen argument is not a valid part of the user address 
space, the namelen argument is too small, the name argument 
contains incorrect address format for the associated address family, or 
the first two bytes of the memory block specified by name do not 
match the address family associated with the socket descriptor s. 


Function is invoked when a callback is in progress. 
socket is already bound to an address. 
Not enough buffers available, too many connections. 


Descriptor is not a socket. 


Version : Requires Windows Sockets 2.0. 
Header: Declared in Wséspi.h. 


WSPConnect, WSPListen, WSPGetSockName, WSPSetSockOpt, WSPSocket 


WSPCancelBlockingCall 


The WSPCancelBlockingCall function cancels a piocRng call that is currently i in 


progress. 
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Parameters 


loErrno 
[out] Pointer to the error code. 


Return Values 


The value returned by WSPCancelBlockingCall is zero if the operation was 
successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a 
specific error code is available in /pErrno. 


Remarks 


This function cancels any outstanding blocking operation for this thread. It is typically 
used in two situations: 


e A Windows Sockets SPI client is processing a message that has been received while 
a service provider is implementing pseudo blocking. In this case, WSAIsBlocking will 
be true. 


e A blocking call is in progress and the Windows Sockets service provider has called 
back to the Windows Sockets SPI client’s blocking hook function (through the callback 
function retrieved from WPUQueryBlockingCallback), which in turn is invoking this 
function. Such a situation might arise, for instance, in implementing a Cancel option 
for an operation that requires an extended time to complete. 


In each case, the original blocking call will terminate as soon as possible with the error 
WSAEINTR. (In the first instance the termination will not take place until Windows 
message scheduling has caused control to revert back to the pseudo blocking routine in 
Windows Sockets. In the second instance, the blocking call will be terminated as soon as 
the blocking hook function completes.) 7 | 


In the case of a blocking WSPConnect operation, Windows Sockets will terminate the 
blocking call as soon as possible, but it cannot be possible for the socket resources to 
be released until the connection has completed (and then been reset) or timed out. This 
is likely to be noticeable only if the Windows Sockets SPI client immediately tries to open 
a new socket (if no sockets are available), or to connect to the same peer eee a 
WSPConnect call. , 


Canceling a WSPAccept or a WSPSelect call does not adversely impact the sockets 
passed to these calls. Only the particular call fails; any operation that was legal before 
the cancel Is legal after the cancel, and the state of the socket is not affected in any way. 


Canceling any operation other than WSPAccept and WSPSelect can leave the socket 
in an indeterminate state. If a Windows Sockets SPI client cancels a blocking operation 
on a socket, the only operation the Windows Sockets SPI client will be able to perform 
on the socket is a call to WSPCloseSocket, although other operations can work on 
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some Windows Sockets service providers. If a Windows Sockets SPI client requires 
maximum portability, it must be careful not to depend on performing operations after a 
cancel operation. A Windows Sockets SPI client can reset the connection by setting the 
time-out on SO_LINGER to zero and calling WSPCloseSocket. 


If a cancel operation compromised the integrity of aSOCK_STREAM’s data stream in 
any way, the Windows Sockets provider will reset the connection and fail all future 
operations other than WSPCloseSocket with WSAECONNABORTED. 


Remarks 


It is acceptable for WSPCancelBlockingCall to return successfully if the blocking 
network operation completes prior to being canceled. In this case, the blocking operation 
will return successfully as if WSPCancelBlockingCall had never been called. The only 
way for the Windows Sockets SPI client to know with certainty that an operation was 
actually canceled is to check for a return code of WSAEINTR from the blocking call. 


Error Codes 
Error code Meaning 
WSAENETDOWN __ Network subsystem has failed. 
WSAEINVAL Indicates there is no outstanding blocking call. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPCleanup 


The WSPCleanup function terminates use of the Windows Sockets service provider. 


Parameters 


loErrno 
[out] Pointer to the error code. 


Return Values 


The return value is zero if the operation has been successfully initiated. Otherwise, the 
value SOCKET_ERROR is returned, and a specific error number is available in /pErrno. 
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Remarks 


The Windows Sockets 2 SPI client is required to perform a successful WSPStartup call 
before it can use Windows Sockets service providers. When it has completed the use of 
Windows Sockets service providers, the SPI client will call WSPCleanup to deregister 
itself from a Windows Sockets service provider and allow the service provider to free any 
resources allocated on behalf of the Windows Sockets 2 client. It is permissible for SPI 
clients to make more than one WSPStartup call. For each WSPStartup call, a 
corresponding WSPCleanup call will also be issued. Only the final WSPCleanup for the 
service provider does the actual cleanup; the preceding calls simply decrement an 
internal reference count in the Windows Sockets service provider. © 


When the internal reference count reaches zero and actual cleanup operations 
commence, any pending blocking or asynchronous calls issued by any thread in this 
process are canceled without posting any notification messages or signaling any event 
objects. Any pending overlapped send and receive operations (WSPSend, | 
~WSPSendTo, WSPRecv, WSPRecvFrom with an overlapped socket) issued by any 
thread in this process are also canceled without setting the event object or invoking the 
completion routine, if specified. In this case, the pending overlapped operations fail with 
the error status WSA_OPERATION_ABORTED. Any sockets open when WSPCleanup 
is called are reset and automatically deallocated as if WSPClosesocket was called; 

_ sockets that have been closed with WSPCloseSocket but still have pending data to be 
sent are not affected—the pending data is still sent. | 


This function should not return until the service provider DLL is prepared to be unloaded 
from memory. In particular, any data remaining to be transmitted must either already — 

have been sent or be queued for transmission by portions of the transport stack that will 
not be unloaded from memory along with the service proviest> DELLE | 7 


Remarks 


A Windows Sockets service provider must be prepared to deal with a process thal 
terminates without invoking WSPCleanup (for example, as a result of an error). A 
Windows Sockets service provider must ensure that WSPCleanup leaves things in a 
state in which the Ws2_32.dll can immediately invoke WSPStartup to reestablish 
Windows Sockets usage 


Error Codes 
_ Error code Meaning ae 
WSANOTINITIALISED A successful wsPStartup call must occur before using this 
function. | 
WSAENETDOWN e Network subsystem has failed. ee 
WSAEINVAL Provider identifier given to the name-space provider’ is not 


eee PY the name- Bpace provider 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPStartup, WSPClosesocket, WSPShutdown 


WSPCloseSocket | 


The WSPCloseSocket function closes a socket. 


Parameters 
S 


[in] Descriptor identifying a socket. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPCloseSocket returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /oErrno. 


Remarks 


This function closes a socket. More precisely, it releases the socket descriptor s, so 
further references to s should fail with the error WSAENOTSOCK. If this is the last 
reference to an underlying socket, the associated naming information and queued data 
are discarded. Any blocking or asynchronous calls pending on the socket (issued by any 
thread in this process) are canceled without posting any notification messages. Any 
pending overlapped operations issued by any thread in this process are also canceled. 
Whatever completion action was specified for these overlapped operations is performed 
(for example, event, completion routine, or completion port). In this case, the pending 
overlapped operations fail with the error status WSA_OPERATION_ABORTED. 
FD_CLOSE will not be posted after WSPCloseSocket is called. 


WSPClosesocket behavior is summarized as follows: 


e If SO_DONTLINGER is enabled (the default setting), WSPCloseSocket returns 
immediately and connection is gracefully closed in the background. 
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e |f SO_LINGER is enabled with a zero time-out, WSPCloseSocket returns 
immediately and the connection is reset/terminated. 


or | 

e If SO_LINGER is enabled with a nonzero time-out with a blocking socket, 
WSPCloseSocket blocks until all data is sent or the time-out expires. 

e If SO_LINGER is enabled with a nonzero time-out with a nonblocking socket, 
WSPCloseSocket returns immediately, thus indicating failure. 


The semantics of WSPCloseSocket are affected by the socket options SO_LINGER 
and SO_DONTLINGER as follows. 


Option Interval Type of close Wait for close? 
SO_DONTLINGER Do not care Graceful No 

SO LINGER | Zero Hard No — 
SO_LINGER -— Nonzero Graceful Yes 


If SO_LINGER is set (that is, the |_onoff member of the linger structure is nonzero) and 

_ the time-out interval, /_linger, is zero, WSPClosesocket is not blocked even if queued 
data has not yet been sent or acknowledged. This is called a hard or abortive close, 
because the socket’s virtual circuit is reset immediately, and any unsent data is lost. Any 
WSPRecv call on the remote side of the circuit will fail with WGAECONNRESET. 


lf SO_LINGER is set with a nonzero time-out interval on a blocking socket, the 
WSPClosesocket call blocks on a blocking socket until the remaining data has been 
sent or until the time-out expires. This is called a graceful disconnect. If the time-out 

~ expires before all data has been sent, the service provider should terminate the 
connection before WSPClosesocket returns. } 


Enabling SO_LINGER with a nonzero time-out interval on a nonblocking socket is not 
recommended. In this case, the call to WSPClosesocket will fail with an error of 
WSAEWOULDBLOCK if the close operation cannot be completed immediately. If 
WSPClosesocket fails with WSAEWOULDBLOCK, the socket handle is still valid and 
a disconnect is not initiated. 


The Windows Sockets SPI client must call WSPClosesocket again to close the socket, 
although WSPClosesocket can continue to fail unless the Windows Sockets SPI client 
does one of the following: | 

¢ Disables SO_DONTLINGER. 

e Enables SO_LINGER with a zero time-out. 

¢ Calls WSPShutdown to initiate closure. 


If SO_DONTLINGER is set on a stream socket (that is, the |_onoff member of the linger 
structure is zero), the WSPClosesocket call will return immediately and does not get 
WSAEWOULDBLOCK, whether the socket is blocking or nonblocking. However, any 
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data queued for transmission will be sent if possible before the underlying socket 
is closed. This is called a graceful disconnect and is the default behavior. 


Note that in this case the Windows Sockets provider is allowed to retain any resources 
associated with the socket until such time as the graceful disconnect has completed 
or the provider terminates the connection due to an inability to complete the operation 
in a provider-determined amount of time. This can affect Windows Sockets clients that 


expect to use all available sockets. This is the default behavior; SO_DONTLINGER 
is set by default. 


Error Codes 
Error code Meaning | 
WSAENETDOWN Network subsystem has failed. 


WSAEINPROGRESS Blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. 


WSAENOTSOCK Descriptor is not a socket. 


WSAEWOULDBLOCK _ Socket is marked as nonblocking and SO_LINGER is set to a 
nonzero time-out value. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPAccept, WSPSocket, WSPloctl, WSPSetSockOpt 


WSPConnect 


The WSPConnect function establishes a connection to a peer, exchanges connect data, 
and specifies needed quality of service based on the supplied flow specification. 
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Parameters 


S a 
[in] Descriptor identifying an unconnected socket. 


name 
[in] Name of the peer to which the socket is to be connected. 


namelen 
[in] Length of the name. 


loCallerData — 
[in] Pointer to the user data that is to be transferred to the peer during connection 
establishment. 


IpCalleeData | 
[out] Pointer to a buffer into which any user data received from the peer ening 
connection establishment can be copied. 


IpSQOS — 
[in] Pointer to the flow specifications for socket s, one on each direction. 


IpGQOS 
[in] Reserved. 
IpErno 
lout] Pointer to the error code. 


Return Values — : 
If no error occurs, WSPConnect returns zero. Otherwise, it returns SOCKET _ERROR, 
and a specific error code is available in /oErrno. 


On a blocking socket, the return value indicates success or failure of the connection 
attempt. If the return error code indicates the connection attempt failed (that is, 
WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the Windows 
Sockets SPI client can call WSPConnect again for the same socket. 


Remarks ot 

This function is used to create a connection to the specified destination and to perform 

a number of other ancillary operations that occur at connect time as well. If the socket, 

s, is unbound, unique values are assigned to the local association by the system and the 
socket is marked as bound. | 


For connection-oriented sockets (for example, type SOCK_STREAM), an active — 
connection is initiated to the specified host using name (an address in the name space 
of the socket. (For a detailed description, see WSPBind.) When this call completes 
successfully, the socket is ready to send and receive data. If the address member of the 
~ name structure is all zeroes, WSPConnect will return the error WSAEADDRNOTAVAIL. 
Any attempt to reconnect an active connection will fail with the error code 
WSAEISCONN. , 
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For connection-oriented, nonblocking sockets it is often not possible to complete the 
connection immediately. In such a case, this function returns with the error 
WSAEWOULDBLOCK but the operation proceeds. When the success or failure outcome 
becomes known, it may be reported in one of several ways depending on how the client 
registers for notification. If the client uses WSPSelect, success is reported in the writefds 
set and failure is reported in the exceptfds set. If the client uses WSPAsyncSelect or 
WSPEventSelect, the notification is announced with FD_CONNECT and the error code 
associated with the FD_CONNECT indicates either success or a specific reason for 
failure. 


For a connectionless socket (for example, type SOCK_DGRAM), the operation 
performed by WSPConnect is to establish a default destination address so the socket 
can be used with subsequent connection-oriented send and receive operations 
(WSPSend,WSPRecv). Any datagrams received from an address other than the 
destination address specified will be discarded. If the address member of the name 
structure is all zeroes, the socket will be disconnected—the default remote address will 
be indeterminate, so WSPSend and WSPRecv calls will return the error code 
WSAENOTCONN. However, WSPSendTo and WSPRecvFrom can still be used. The 
default destination can be changed by simply calling WSPConnect again, even if the 
socket is already connected. Any datagrams queued for receipt are discarded if name is 
different from the previous WSPConnect. 


For connectionless sockets, name can indicate any valid address, including a broadcast 
address. However, to connect to a broadcast address, a socket must have 
WSPSetSockOpt SO_BROADCAST enabled. Otherwise, WSPConnect will fail with the 
error code WSAEACCES. | 


On connectionless sockets, exchange of user-to-user data is not possible and the 
corresponding parameters will be silently ignored. 


The Windows Sockets SPI client is responsible for allocating any memory space pointed 
to directly or indirectly by any of the parameters it specifies. 


The /pCallerData is a value parameter that contains any user data to be sent along with 
the connection request. If joCallerData is NULL, no user data will be passed to the peer. 
The |pCalleeDaia is a result parameter that will reference any user data passed back 
from the peer as part of the connection establishment. The /oCalleeData->len initially 
contains the length of the buffer allocated by the Windows Sockets SPI client and 
pointed to by /pCalleeData->buf. The |pCalleeData->len will be set to zero if no user data 


_ has been passed back. The /pCalleeData information will be valid when the connection 


operation is complete. For blocking sockets, this will be when the WSPConnect function 
returns. For nonblocking sockets, this will be after the FD_CONNECT notification has 
occurred. If /oCalleeData is NULL, no user data will be passed back. The exact format 
of the user data is specific to the address family the socket belongs to and/or the 
applications involved. 


At connect time, a Windows Sockets SPI client can use the /pDSQOS parameter 
to override any previous QOS specification made for the socket through WSPloctl 
with the SIO_SET_QOS opcode. 
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The IpSQOS specifies the flow specifications for socket s, one for each direction, 
followed by any additional provider-specific parameters. If either the associated transport 
provider in general or the specific type of socket in particular cannot honor the QOS 
request, an error will be returned as indicated below. The sending or receiving flow 
specification values will be ignored, respectively, for any unidirectional sockets. 

If no provider-specific parameters are supplied, the buf and /en members of 
IDSQOS->ProviderSpecific should be set to NULL and zero, respectively. A NULL value 
for |pDSQOS indicates that no application supplied quality of service. 


Note When connected sockets break (that is, become closed for whatever reason), 
they should be discarded and recreated. It is safest to assume that when things go awry 
for any reason on a connected socket, the Windows Sockets SPI client must discard and 


recreate the needed sockets in order to return to a stable point. 


Error Codes 
Error code Meaning 
WSAENETDOWN Network subsystem has failed. 


WSAEADDRINUSE 


WSAEINTR 
WSAEINPROGRESS 


Local address of the socket is already in use and the socket was | 
not marked to allow address reuse with SO_LREUSEADDR. This 
error usually occurs at the time of bind, but could be delayed until 
this function if the bind was to a partially wildcard address 
(involving ADDR_ANY) and if a specific address needs to De 
committed at the time of this function.. 


(Blocking) call was canceled through WSPCancelBlockingCall. | 


Blocking Windows Sockets call is in progress or the service — 
provider is still processing a callback function. a 


WSAEALREADY Nonblocking WSPConnect call is in progress on the specified 
socket. 
In order to preserve backward compatibility, this error is reported 
as WSAEINVAL to Windows Sockets 1.1 applications that link to 

| | either Winsock.dll or Wsock32.dll. 

WSAEADDRNOTAVAIL Remote address is not a valid address (for example, ADDR_ANY). 

~ WSAEAFNOSUPPORT Addresses in the specified family cannot be used with this socket. 
WSAECONNREFUSED Attempt to connect was rejected. | 
WSAEFAULT Name or the namelen argument is not a valid part of the user 
| address space, the namelen argument is too small, the buffer 

length for /oCalleeData, |IpSQOS, and |pGQOS is too small, or the _ 
buffer length for /pCallerData is too large. 

WSAEINVAL Parameter sis a listening socket. | 

WSAEISCONN Socket | is areagy connected (connection: -oriented sockets only). 


_ (continued) 
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(continued) 
Error code Meaning 
WSAENETUNREACH Network cannot be reached from this host at this time. 
WSAENOBUFS No buffer space is available. The socket cannot be connected. 
WSAENOTSOCK, Descriptor is not a socket. 
WSAEOPNOTSUPP Flow specifications specified in JoSQOS cannot be satisfied. 
WSAEPROTONOSUPPORT _ The /pCallerData augment is not supported by the 

service provider. 

WSAETIMEDOUT Attempt to connect timed out without establishing a connection. 
WSAEWOULDBLOCK Socket is marked as nonblocking and the connection cannot be 


completed immediately. It is possible to select the socket using the 
WSPSelect function while it is connecting by using the 
WSPSelect function to select it for writing. 


WSAEACCES Attempt to connect datagram socket to broadcast address failed 
because WSPSetSockOpt SO_BROADCAST is not enabled. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPAccept, WSPBind, WSPGetSockName, WSPGetSockOpt, WSPSocket, 
WSPSelect, WSPEventSelect, WSPEnumNetworkEvents 


WSPDuplicateSocket 


The WSPDuplicateSocket function returns a WSAPROTOCOL_INFOW structure that 
can be used to create a new socket descriptor for a shared socket. 


Parameters 
S 


[in] Specifies the local socket descriptor. 


dwProcessid — | 
[in] Specifies the identifier of the target process for which the shared socket will be 


used. 
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pProtocolinfo | 
[out] Pointer to a buffer allocated by the client that is large enough to contain 
a WSAPROTOCOL_INFOW structure. The service provider copies the protocol 
information structure contents to this buffer. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPDuplicateSocket returns zero. Otherwise, the value of 
SOCKET_ERROR is returned, and a specific error number is available in /pErrno. 


Remarks 

A source process calls WSPDuplicateSocket to obtain a special 
WSAPROTOCOL_INFOW structure. It uses some interprocess communications (IPC) 
mechanism to pass the contents of this structure to a target process, which in turn uses 
it in a call to WSPSocket to obtain a descriptor for the duplicated socket. Note that the 
special WSAPROTOCOL_INFOW structure can only be used once by the target 
process. | | | 


It is the service provider’s responsibility to perform whatever operations are needed 

in the source process context and to create a WSAPROTOCOL_INFOW structure that 
will be recognized when it subsequently appears as a parameter to WSPSocket in the 
target processes’ context. The provider must then return a socket descriptor that 
references a common underlying socket. The dwProviderReserved member of the 
-WSAPROTOCOL_INFOW structure is available for the service provider's use and 

can be used to store any useful context information, including a duplicated handle. 


When new socket descriptors are allocated, IFS providers must call a 
-WPUModifyIFSHandle and non-IFS providers must call WPUCreateSocketHandle. 


One possible scenario for establishing and using a shared socket in a handoff mode 
is illustrated in the following. 7 


Source process Z IPC Destination process 
1) WSPSocket, WSPConnect. | 


2) Requests target process identifier. => | ne | 
fees | woe | = 3) Receives process identifier 
| aes request and respond. 

4) Receives process identifier. = | ie 
5) Calls WSPDuplicateSocket to get a 

_ Special WSAPROTOCOL_INFOW structure. 
6) Sends WSAPROTOCOL_INFOW 
structure totarget. = | | 
| (continued) _ 
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(continued) | 
Source process | IPC Destination process 


= 7) Receives 
WSAPROTOCOL_INFOW 
structure. 


8) Calls WSPSocket to create 
shared socket descriptor. 


10) WSPClosesocket | _ 9) Uses shared socket for data 
| exchange. 


The descriptors that reference a shared socket can be used independently as far 

~ as I/O is concerned. However, the Windows Sockets interface does not implement 
any type of access control, so it is up to the processes involved to coordinate their 
operations on a shared socket. A typical use for shared sockets is to have one process 
that is responsible for creating sockets and establishing connections, hand off sockets 
to other processes that are responsible for information exchange. 


Since what is duplicated are the socket descriptors and not the underlying socket, all 
the states associated with a socket are held in common across all the descriptors. 
For example a WSPSetSockOpt operation performed using one descriptor 

is subsequently visible using a WSPGetSockOpt from any or all descriptors. 

A process can call WSPClosesocket on a duplicated socket and the descriptor will 
become deallocated. The underlying socket, however, will remain open until 
WSPClosesocket is called by the last remaining descriptor. 


Notification on shared sockets is subject to the usual constraints of WSPAsyncSelect 
and WSPEventSelect. Issuing either of these calls using any of the shared descriptors 
cancels any previous event registration for the socket, regardless of which descriptor 
was used to make that registration. Thus, for example, a shared socket cannot deliver 
FD_READ events to process A and FD_WRITE events to process B. For situations 
when such tight coordination is required, it is suggested that developers use threads 
instead of separate processes. 


_ A layered service provider supplies an implementation of this function, but it is also 
a Client of this function if and when it calls WSPDuplicateSocket of the next layer in 
the protocol chain. Some special considerations apply to this function’s /oProtocollnfo 
parameter as it is propagated down through the layers of the protocol chain. 


If the next layer in the protocol chain is another layer then when the next layer’s 
WSPDuplicateSocket is called, this layer must pass to the next layer a /pProtocolinfo 
that references the same unmodified WSAPROTOCOL_INFOW structure with the same 
unmodified chain information. However, if the next layer is the base protocol (that is, 
the last element in the chain), this layer performs a substitution when calling the base 
providers WSPDuplicateSocket. In this case, the base provider's | 
WSAPROTOCOL_INFOW structure should be referenced by the /pProtocolinfo 
parameter. 
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One vital benefit of this policy is that base service providers do not have to be aware 

of protocol chains. This same policy applies when propagating a 
WSAPROTOCOL_INFOW structure through a layered sequence of other functions such 
as WSPAddressToString, WSPStartup, WSPSocket, or WSPStringToAddress. 


Error Codes 

Error code Meaning 

WSAENETDOWN Network subsystem has failed. 

WSAEINVAL | Indicates that one of the specified parameters was invalid. 


WSAEINPROGRESS _ Blocking Windows Sockets call is in progress or the service 
provider is still processing a callback function. 


WSAEMFILE No more socket descriptors are available. 
WSAENOBUFS No buffer space is available. The socket cannot be created. 
WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WPUCreateSocketHandle, WPUModifyIFSHandle | 


WSPEnumNetworkEvents 


The WSPEnumNetworkEvents function reports occurrences of network events for the 
indicated socket. 3 | 


Parameters 
S 


in] Descriptor identifying the socket. 


hEventObject | 
in] An optional handle identifying an associated event object to be reset. 
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loNetworkEvents | 
[out] Pointer toa WSANETWORKEVENTS structure that is filled with a record 
of occurred network events and any associated error codes. | 
~The WSANETWORKEVENTS structure is defined in the ae text. 


IpErrno 
[out] Pointer to the error code. 


Return Values 


The return value is zero if the operation was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number is available in /oErrno. 


Remarks 


This function is used to report which network events have occurred for the indicated 
socket since the last invocation of this function. It is intended for use in conjunction with 
WSPEventSelect, which associates an event object with one or more network events. 
Recording of network events commences when WSPEventSelect is called with a 
nonzero /NetworkEvents parameter and remains in effect until another call is made to 
WSPEventSelect with the /NetworkEvents parameter set to zero, or until a call is made 
to WSPAsyncSelect. | 


WSPEnumNetworkEvents only reports network activity and errors nominated through 
WSPEventSelect. See the descriptions of WSPSelect and WSPAsyncSelect to find out 
how those functions report network activity and errors. 


The socket’s internal record of network events is copied to the structure referenced by 
loNetworkEvents, whereafter the internal network events record is cleared. If 
hEventObject is non-NULL, the indicated event object is also reset. The Windows 
Sockets provider guarantees that the operations of copying the network event record, 
clearing it, and resetting any associated event object are atomic, such that the next 
occurrence of a nominated network event will cause the event object to become set. In 
the case of this function returning SOCKET_ERROR, the associated event object is not 


reset and the record of network events is not cleared. 


The WSANETWORKEVENTS structure is defined as follows: 


The INetworkEvent member of the structure indicates which of the FD_XXX network 
events have occurred. The iErrorCode array is used to contain any associated error 
codes, with array index corresponding to the position of event bits in INetworkEvents. 
The identifiers such as FD_READ_BIT and FD_WRITE_BIT can be used to index the 
peTrorvede array. 
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Note that only those elements of the iErrorCode array are set that correspond to the bits 
set in INetworkEvents member. Other members are not modified (this is important for 
backward compatibility with the Windows Socket 2 SPI clients that are not aware of new 
FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events). 


The following error codes can be returned along with the respective network event. 


Event: FD_CONNECT 


Error Code 


WSAEAFNOSUPPORT 


WSAECONNREFUSED 
WSAENETUNREACH 
WSAENOBUFS 


WSAETIMEDOUT 


Event: FD_CLOSE 
Error Code 


WSAENETDOWN 
WSAECONNRESET 
WSAECONNABORTED 


Event: FD_READ 
Event: FD_WRITE 
Event: FD_OOB 
Event: FD_ACCEPT 
Event: FD_QOS 


Event: FD GROUP_QOS 


Meaning 


Addresses in the specified family cannot be used with this 
socket. 


Attempt to connect was forcefully rejected. 
Network cannot be reached from this host at this time. 


No buffer space is available. The socket cannot be 
connected. 


Attempt to connect timed out without establishing a 
connection. 


Meaning 


Network subsystem has failed. 
Connection was reset by the remote side. 4 
Connection was terminated due to a time-out or other failure. 


Event: FD_ADDRESS_LIST_CHANGE 
Event: FD_ROUTING_INTERFACE_CHANGE 


Error Code — 


Meaning 


WSAENETUNREACH __ Specified destination is no longer reachable. 


WSAENETDOWN 


Network subsystem has failed. 


576 Volume 1 Winsock and QOS 


Error Code — Meaning 

WSAENETDOWN Network subsystem has failed. 

Error Code 

Error code | Meaning 

WSAENETDOWN Network subsystem has failed. 
-WSAEINVAL Indicates that one of the specified parameters was invalid. 


WSAEINPROGRESS __ A blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. 


WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPEventSelect 


WSPeEventSelect 


The WSPEventSelect function specifies an event object to be associated with the 
supplied set of network events. 


Parameters 
S 


[in] Descriptor identifying the socket. 


hEventObject | 
[in] Handle identifying the event object to be associated with the supplied set of 
network events. 


INetworkEvents « | : 3 
[in] Bitmask that specifies the combination of network events in which the Windows 
Sockets SPI client has interest. 


Chapter 11. Winsock 2 SPI Reference 577 


lpErrno 
[out] Pointer to the error code. 


Return Values 


The return value is zero if the Windows Sockets SPI client’s specification of the network 
events and the associated event object was successful. Otherwise, the value 
SOCKET_ERROR is returned, and a specific error number is available in /oErrno. 


Remarks 


This function is used to specify an event object, hEventObject, to be associated with the 
selected network events, /NetworkEvents. The socket for which an event object is 
specified is identified by s. The event object is set when any of the nominated network 
events occur. 


WSPEventSelect operates very similarly to WSPAsyncSelect, the difference being in 
the actions taken when a nominated network event occurs. Whereas WSPAsyncSelect 
causes a Windows Sockets SPI client-specified Windows message to be posted, 
WSPEventSelect sets the associated event object and records the occurrence of this 
event in an internal network event record. A Windows Sockets SPI client can use 
WSPEnumNetworkEvents to retrieve the contents of the internal network event record 
and thus determine which of the nominated network events have occurred. 


~ WSPEventSelect is the only function that causes network activity and errors to be 
recorded and retrievable through WSPEnumNetworkEvents. See the descriptions of 
WSPSelect and Moree neoe ee to find out how those functions report network 
activity and errors. | 


This function automatically sets socket s to nonblocking mode, regardless of the value of 
INetworkEvents. 


The /NetworkEvents parameter is constructed by using the bitwise OR operator with any 
of the values specified in the following table. , 


Value | Meaning 
FD_READ Issues notification of readiness for reading. 
FD_WRITE | Issues notification of readiness for writing. 
FD_OOB ee Issues notification of the arrival of OOB data. 
FD_ACCEPT _ Issues notification of incoming connections. 

| FD_CONNECT oa Issues notification of completed connection. 
FD_CLOSE ae Issues notification of socket closure. 
FD_QOS | gan? Issues. notification of socket aes) changes. 


FD_GROU P_QOS _ Reserved. 


(continued) 
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(continued) 

Value Meaning 

FD_ROUTING_ Issues notification of routing interface changes for the 
INTERFACE_CHANGE _ specified destination(s). 

FD_ADDRESS_ Issues notification of local address list changes for the 
LIST_CHANGE socket’s address family. 


Issuing a WSPEventSelect for a socket cancels any previous WSPAsyncSelect or 
WSPEventSelect for the same socket and clears the internal network event record. For 
example, to associate an event object with both reading and writing network events, the 
Windows Sockets SPI client must call WSPEventSelect with both FD_READ and 
FD_WRITE, as follows: 


It is not possible to specify different event objects for different network events. The 
following code will not work; the second call will cancel the effects of the first, and only 
FD_WRITE network event will be associated with hEventObject2: 


To cancel the association and selection of network events on a socket, /NetworkEvents 
should be set to zero, in which case the hEventObject parameter will be ignored. 


Closing a socket with WSPCloseSocket also cancels the association and selection of 
network events specified in WSPEventSelect for the socket. The Windows Sockets SPI 
client, however, still must call WSACloseEvent to explicitly close the event object and 
free any resources. 


Since an accepted (WSPAccept) socket has the same properties as the listening socket 
used to accept it, any WSPEventSelect association and network events selection set for 
the listening socket apply to the accepted socket. For example, if a listening socket has 
WSPEventSelect association of hEventOject with FD_ACCEPT, FD_READ, and 
FD_WRITE, then any socket accepted on that listening socket will also have 
FD_ACCEPT, FD_READ, and FD_WRITE network events associated with the same 
hEventObject. \f a different hEventObject or network events are needed, the Windows 
Sockets SPI client should call WSPEventSelect, passing the accepted socket and the 
new information. 


Note Having successfully recorded the occurrence of the network event and signaled 
the associated event object, no further actions are taken for that network event until the 
Windows Sockets SPI client makes the function call that implicitly reenables the setting 
of that network event and the signaling of the associated event object. 
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Network event Reenabling function 

FD _READ WSPRecv or WSPRecvFrom 
FD_WRITE WSPSend or WSPSendTo 
FD_OOB WSPRecv or WSPRecvFrom 


FD_ACCEPT WSPAccept unless the error code returned is 
| WSATRY_AGAIN indicating that the condition function 
returned CF_DEFER 


FD_CONNECT None 

FD_CLOSE None 

FD_QOS WSPloctl with SIO_QOS 

FD_GROUP_QOS Reserved 

-FD_ROUTING__ WSPloctl with command 

INTERFACE_CHANGE SIO_ROUTING_INTERFACE_CHANGE 

FD ADDRESS __ WSPloctl with command SIO_ADDRESS_LIST_CHANGE 
LIST _CHANGE 


Any call to the reenabling routine, even one that fails, results in reenabling of recording 
and signaling for the relevant network event and event object, respectively. 


For FD_READ, FD_OOB, and FD_ACCEPT network events, network event recording 
and event object signaling are level-triggered. This means that if the reenabling routine 
is called and the relevant network condition is still valid after the call, the network event 
is recorded and the associated event object is signaled. This allows a Windows Sockets 
SPI client to be event-driven and not be concerned with the amount of data that arrives 

~ at any one time. This is illustrated by the following sequence. 


e Service provider receives 100 bytes of data on socket s, records the FD_READ 
network event and signals the associated event object. 


e The Windows Sockets SPI client issues WSPRecv( s, buffptr, 50, 0) to read 50 bytes. 


e The service provider records the FD_READ network event and signals the associated 
event oniec again since there is still data to be read. 


With these semantics, a Windows Sockets SPI client need not read all available data in 
response to an FD_READ network event—a single WSPRecv in response to each 
FD_READ network event is appropriate. 


The FD_QOS event is considered edge triggered. A message will be goose exactly 
once when a QOS change occurs. Further indications will not be issued until either the 
service provider detects a further change in quality of service or the Windows Sockets 
SPI client renegotiates the quality of service for the socket. 


The FD_ROUTING_INTERFACE_CHANGE and FD _ADDRESS__ LIST_ CHANGE events | 
are considered edge triggered as well. A message will be posted exactly once when a 
change occurs AFTER the Windows Socket SPI client has requested the notification by 
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issuing WSAloctl with SIO_ROUTING_INTERFACE_CHANGE or 
SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be 
forthcoming until the SPI client reissues the lOCTL and another change is detected since 
the IOCTL has been issued. 


lf a network event has already occurred when the Windows Sockets SPI client calls 
WSPEventSelect or when the reenabling function is called, then a network event is 
recorded and the associated event object is signaled as appropriate. This is illustrated in 
the following sequence. 


e A Windows Sockets SPI client calls WSPListen. 
e Aconnect request is received but not yet accepted. 


e The Windows Sockets SPI client calls WSPEventSelect specifying that it is interested 
in the FD_ACCEPT network event for the socket. The service provider records the 
FD_ACCEPT network event and signals the associated event object immediately. 


The FD_WRITE network event is handled slightly differently. An FD_WRITE network 
event is recorded when a socket is first connected with WSPConnect or accepted with 
WSPAccept, and then after a WSPSend or WSPSendTo fails with 
WSAEWOULDBLOCK and buffer space becomes available. Therefore, a Windows 
Sockets SPI client can assume that sends are possible starting from the first FD_WRITE 
network event setting and lasting until a send returns WSAEWOULDBLOCK. After such 
a failure the Windows Sockets SPI client will find out that sends are again possible when 
an FD_WRITE network event is recorded and the associated event object is signaled. 


The FD_OOB network event is used only when a socket is configured to receive OOB 
data separately. If the socket is configured to receive OOB data inline, the OOB 
(expedited) data is treated as normal data and the Windows Sockets SPI client should 
register an interest in, and will get, FD_READ network event, not FD_OOB network 
event. A Windows Sockets SPI client can set or inspect the way in which OOB data is to 
be handled by using WSPSetSockOpt or WSPGetSockOpt for the 

SO_OOBINLINE option. 


The error code in an FD_CLOSE network event indicates whether the socket close was 
graceful or abortive. If the error code is zero, then the close was graceful; if the error 
code is WSAECONNRESET, then the socket’s virtual circuit was reset. This only applies 
to connection-oriented sockets such as SOCK_STREAM. 


The FD_CLOSE network event is recorded when a close indication is received for the 
virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE 
is recorded when the connection goes into the FIN WAIT or CLOSE WAIT states. This 
results from the remote end performing a mer onuiconn on the send side or a 
WSPCloseSocket. 


Service providers shall record only an FD CLOSE: network event to indicate closure of a 
virtual circuit, they must not record an FD_READ network event to indicate this condition. 
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The FD_QOS network event is recorded when any member in the flow specification 
associated with socket s has changed. This change must be made available to Windows 
Sockets SPI clients through the WSPloctl function with SIO_GET_QOS to retrieve the 
current quality of service for socket s. 


The FD_ROUTING_INTERFACE_CHANGE network event is recorded when the local 
interface that should be used to reach the destination specified in WSAloctl with 
SIO_ROUTING_INTERFACE_CHANGE changes AFTER such IOCTL has been issued. 


The FD_ADDRESS_LIST_CHANGE network event is recorded when the list of 
addresses of socket’s protocol family to which the Windows Socket SPI client can bind 
changes after WSAloctl with SIO_LADDRESS_LIST_CHANGE has been issued. 


Error Codes , 

Error code Meaning 

WSAENETDOWN Network subsystem has failed. 

WSAEINVAL Indicates that one of the specified parameters was invalid, or 


the specified socket is in an invalid state. 


WSAEINPROGRESS __ Blocking Windows Sockets call is in progress or the service 
provider is still processing a callback function. 


WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPEnumNetworkE vents 


WSPGetOverlappedResult 


The WSPGetOverlappedResult function returns the results of an overlapped operation 
on the specified socket. 
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Parameters 
Ss se | 
[in] Identifies the socket. This is the same socket that was specified when the 
overlapped operation was started by a call to WSPRecv, WSPRecvFrom, WSPSend, 
WSPSendTo, or WSPloctl. | 


lpOverlapped | 
[in] Points to a WSAOVERLAPPED structure that was specified when the overlapped 
operation was started. 


locb Transfer 
[out] Points to a 32-bit variable that receives the number of bytes that were actually 
transferred by a send or receive operation, or by WSPloctl. 


fWait 
_ [in] Specifies whether the function should wait for the pending overlapped operation to 
complete. If TRUE, the function does not return until the operation has been 
completed. If FALSE and the operation is still pending, the function returns FALSE 
and |pErrno is WSA_IO_INCOMPLETE. The fWait parameter may be set to TRUE 
only if the overlapped operation selected event-based completion notification. 


lpdwFlags 
[out] Points to a 32-bit variable that will receive one or more flags that supplement the 
completion status. If the overlapped operation was initiated through WSPRecv or 
WSPRecvFrom, this parameter will contain the results value for joFlags parameter. 
lpErrno 
[out] Pointer to the error code. 


Return Values 


lf WSPGetOverlappedResult succeeds, the return value is TRUE. This means the 
overlapped operation has completed successfully and the value pointed to by 

Ipcb Transfer has been updated. If WSPGetOverlappedResult returns FALSE, this 
means that the overlapped operation has not completed or the overlapped operation 
completed but with errors, or completion status could not be determined due to errors in 
one or more parameters to WSPGetOverlappedResult. On failure, the value pointed to 
by locbTransfer will not be updated. The /pErrno parameter indicates the cause of the 
failure corners of WSPGetOverlappedResult or of the associated overlapped eee 


Remarks 


_ The results reported by the WSPGetOverlappedResult function are those of the 


specified socket’s last overlapped operation to which the specified WSAOVERLAPPED 
structure was provided, and for which the operation’s results were pending. A pending 
operation is indicated when the function that started the operation returns 
SOCKET_ERROR, and the /pErrno is WSA_IO_PENDING. When an I/O operation is 
pending, the function that started the operation resets the hEvent member of the 
WSAOVERLAPPED structure to the nonsignaled state. Then, when the pending 
operation has been completed, the system sets the event object to the signaled state. 
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If the fWait parameter is TRUE, WSPGetOverlappedResult determines whether the 
pending operation has been completed by blocking and waiting for the event object to be 
in the signaled state. A client may set the fWait parameter to TRUE only if it selected 
event-based completion notification when the I/O operation was requested. If another 
form of notification was selected, the usage of the hEvent member of the 
WSAOVERLAPPED structure is different, and setting fWait to TRUE causes 
unpredictable results. 


Interaction with WPUCompleteOverlappedRequest 


The behavior of WPUCompleteOverlappedRequest places some constraints on how a 
service provider implements WSPGetOverlappedResult since only the Offset and 
OffsetHigh members of the WSAOVERLAPPED structure are exclusively controlled by 
the service provider even though three values (byte count, flags, and error) must be 
retrieved from the structure by WSPGetOverlappedResult. A service provider may 

~ accomplish this any way it chooses as long as it interacts with the behavior of 
WPUCompleteOverlappedRequest properly. The following description presents a 
typical implementation: 


At the start of overlapped processing, the service provider sets /nternal to 
WSS_OPERATION_IN_PROGRESS. 


When the I/O operation is complete, the provider sets OffsetHigh to the Windows 
Sockets 2 error code resulting from the operation, sets Offset to the flags resulting from 
the I/O operation, and calls WPUCompleteOverlappedRequest, passing the transfer 
byte count as one of the parameters. WPUCompleteOverlappedRequest eventually 
sets InternalHigh to the transfer byte count, then sets Internal to a value other than 
WSS_OPERATION_IN_PROGRESS. | 


When WSPGetOverlappedResult is called, the service provider checks Internal. If it is 
WSS_OPERATION_IN_PROGRESS, the provider waits on the event handle in the 
hEvent member or returns an error, based on the setting of the fWait flag of 
WSPGetOverlappedResult. If not in progress, or after completion of waiting, the 
provider returns the values from InternalHigh, OffsetHigh, and Offset as the transfer 
count, operation result error code, and flags respectively. 


Error Codes 

Error code | Meaning 

WSAENETDOWN Network subsystem has failed. 
WSAENOTSOCK : Descriptor is nota socket. 


WSA_INVALID_ HANDLE _ The hEvent member of the WSAOVERLAPPED structure 
| | | does not contain a valid event object handle. 
WSA_EINVAL ~ One of the parameters is unacceptable. 


WSA_IO_INCOMPLETE _ The fWait parameter is FALSE and the VO operation has 
| not yet completed. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. | 


WSPRecv, WSPRecvFrom, WSPSend, WSPSendTo, WSPConnect, WSPAccept, 
WSPloctl, WPUCompleteOverlappedRequest 


WSPGetPeerName 


The WSPGetPeerName function gets the address of the peer to which a socket is 
connected. 


Parameters 
S 


[in] Descriptor identifying a connected socket. 


name 
[out] Pointer to the structure to receive the name of the peer. 


namelen | 
[in/out] Pointer to an integer that, on input, indicates the size of the structure pointed 
to by name, and on output indicates the size of the returned name. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPGetPeerName returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /pErrno. 


Remarks 


WSPGetPeerName supplies the name of the peer connected to the socket s and stores 
it in the structure SOCKADDR referenced by name. It can be used only on a connected 
socket. For datagram sockets, only the name of a peer specified in a previous 
WSPConnect call will be returned—any name specified by a previous WSPSendTo cal 
will not be returned by WSPGetPeerName. 


Chapter 11 Winsock 2 SPI Reference 585 


On return, the namelen argument contains the actual size of the name returned in bytes. 


Error Codes 

Error code Meaning 

WSAENETDOWN Network subsystem has failed. 

WSAEFAULT Name or the namelen argument is not a valid part of the user 


address space, or the namelen argument is too small. 
WSAEINPROGRESS _ Function is invoked when a callback is in progress. 
WSAENOTCONN Socket is not connected. 
WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPBind, WSPSocket, WSPGetSockName 


WSPGetQOSByName 


The WSPGetQOSByName function initializes a QOS structure based on a named 
template, or retrieves an enumeration of the available template names. | 


Parameters 


Ss 
[in] Descriptor identifying a socket. 

IpDQOSName 
[in out] Specifies the QOS template name, or supplies a buffer to retrieve an 
enumeration of the available template names. 

IpQOS 
[out] Pointer to the Qos structure to be filled. 


IpErrno 
[out] A pointer to the error code. 
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Return Values 


If the function succeeds, the return value is TRUE. If the function fails, the return value is 
FALSE, and a specific error code is available in /oErrno. 


Remarks 


Clients can use WSPGetQOSByName to initialize a QOS structure to a set of known 
values appropriate for a particular service class or media type. These values are stored 
in a template that is referenced by a well-known name. The client may retrieve these 
values by setting the buf member of the WSABUF indicated by |JpQOSName to point to 
a Unicode string of nonzero length specifying a template name. In this case the usage of 
lpDQOSName is IN only, and results are returned through /pQOS. 


Alternatively, the client may use WSPGetQOSByName to retrieve an enumeration of 
available template names. The client may do this by setting the buf member of the 
WSABUF indicated by |pDQOSName to a zero-length null-terminated Unicode string. In 
this case, the buffer indicated by buf is overwritten with a sequence of as many null- 
terminated Unicode template name strings as are available up to the number of bytes 
available in buf as indicated by the len member of the WSABUF indicated by 
IpDQOSName. The list of names itself is terminated by a zero-length Unicode name 
string. When WSPGetQOSByName is used to retrieve template names, the /opQOS 
parameter is ignored. | 


Error Codes 
Error code Meaning 


WSAENETDOWN __ Network subsystem has failed. 
WSAENOTSOCK Descriptor is not a socket. 


WSAEFAULT The /oQOS argument is not a valid part of the user address space, 
OF the buffer length for /OQOS is too small. 
WSAEINVAL  _ Specified QOS template name is invalid. 


Windows 95/98: Focuires Windows 98. 
Header: Declared in Ws2spi.h. 


WSPConnect, WSPAccept, WSPGetSockOpt 


WSPGetSockName 


The WSPGetSockName function gets the local name for a socket. 
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Parameters 


S 
[in] Descriptor identifying a bound socket. 


name 
[out] Pointer to a structure used to supply the address (name) of the socket. 


namelen 
[in/out] Pointer to an integer that, on input, indicates the size of the structure pointed 
to by name, and on output indicates the size of the returned name. | 


loErrno 
[out] Pointer to the error code. 


Return Values _ oe Rie eg 


If no error occurs, WSPGetSockName returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in IpErrno. 


Remarks | | ees 

WSPGetSockName retrieves the current name for the specified socket descriptor in 
name. It is used on a bound and/or connected socket specified by the s parameter. The 
local association is returned. This call is especially useful wnen a WSPConnect call has 
been made without doing a WSPBind first; as this call provides the only means by which 
the local association that has been set by the service provider can be determined. 


If a socket was bound to an unspecified address (for example, ADDR_ANY), indicating 
that any of the host’s addresses within the specified address family should be used for 
the socket, WSPGetSockName will not necessarily return information about the host 
address, unless the socket has been connected with WSPConnect or WSPAccept. The 
Windows Sockets SPI client must not assume that an address will be specified unless. 
the socket is connected. This is because for a multihomed host, the address that will be 
used for the socket is unknown until the socket is connected. 


Error Codes 

Error code | Meaning 

WSAENETDOWN _ Network subsystem has failed. 
WSAEFAULT _ Name or the namelen argument is not a valid part of the user 


address space, or the namelen argument is too small. 


(continued) 
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(continued) — 

Error code Meaning 

WSAEINPROGRESS _ Function is invoked when a callback is in progress. 
WSAENOTSOCK Descriptor is not a socket. | 

WSAEINVAL Socket has not been bound to an address with WSPBind, or 


ADDR_ANY is specified in WSPBind but connection has not 
yet occurred. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. | 


WSPBind, WSPSocket, WSPGetPeerName 


WSPGetSockOpt 


The WSPGetSockOpt function retrieves a socket option. 


ee oS 


Parameters 


Ss 
[in] Descriptor identifying a socket. 


level 
[in] Level at which the option is defined; the supported levels include SOL_SOCKET. 
See Annex for more protocol-specific levels. | 

optname 
[in] Socket option for which the value is to be retrieved. 


optval 
[out] Pointer to the buffer in which the value for the requested option is to be returned. 


optlen | ‘ 
in/out] Pointer to the size of the optval buffer. 


loErrno 
[out] A pointer to the error code. 


Return Values 


If no error occurs, WSPGetSockOpt returns zero. Otherwise, a value of 
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SOCKET_ERROR is returned, and a specific error code is available in /oErrno. 


Remarks 


WSPGetSockOpt retrieves the current value for a socket option associated with a 
socket of any type, in any state, and stores the result in optval. Options can exist at 
multiple protocol levels, but they are always present at the uppermost socket’ level. 
Options affect socket operations, such as the routing of packets and OOB data transfer. 


The value associated with the selected option is returned in the buffer optval. The 
integer pointed to by optlen should originally contain the size of this buffer; on return, it 
will be set to the size of the value returned. For SO_LINGER,, this will be the size of a 
structure linger; for most other options it will be the size of an integer. 


The Windows Sockets SPI client is responsible for allocating any memory space pointed 
to directly or indirectly by any of the parameters it specifies. 


If the option was never set with WSPSetSockOpt, then WSPGetSockOpt returns the 


default value for the option. 
level = SOL_SOCKET 


Value 


Type 


SO_ACCEPTCONN BOOL 


SO_BROADCAST 
SO_DEBUG 
SO_DONTLINGER 


~ SO_DONTROUTE 


SO_ERROR 


SO_GROUP_ID 


SO_GROUP_ 
PRIORITY 


BOOL 
BOOL 
BOOL 


BOOL 


integer 


GROUP 
integer 


Meaning 


Socket is listening through 
WSPListen. 


Socket is configured for the 
transmission of broadcast 
messages. 

Debugging is enabled. 

lf true, the SO_LINGER option is 
disabled. 


Routing is disabled. Not 
supported on ATM sockets 
(results in an error). 


Retrieves error status and 
clears. 


Reserved. 
Reserved. 


Default 


FALSE unless a 
WSPListen has 
been 

performed. | 


_ FALSE 


FALSE 


TRUE 


FALSE 


Null 
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(continued) 


Value 


SO_KEEPALIVE 


SO_LINGER 


SO_MAX_MSG_ 
SIZE 


SO_OOBINLINE 


SO_PROTOCOL_ 
INFO 


SO_RCVBUF 


SO_REUSEADDR 


SO_SNDBUF 


SO_TYPE 


PVD_ CONFIG 


Type 
BOOL 


LINGER structure 


unsigned integer 


BOOL 


WSAPROTOCOL_ 


INFO structure 


integer 


BOOL 


integer 


integer 


Service Provider 
Dependent 


Meaning 


Keepalives are being sent. Not 
supported on ATM sockets 
(results in an error). 


Returns the current linger 
options. 

Maximum size of a message for 
message-oriented socket types 
(for example, SOCK_DGRAM). 
Has no meaning for stream 
oriented sockets. 


OOB data is being received in 
the normal data stream. 


Description of protocol 
information for protocol that is 
bound to this socket. 

Total per-socket buffer space 
reserved for receives. This is 
unrelated to 
SO_MAX_MSG_SIZE or ‘the 
size of a TCP window. 


Socket can be bound to an 


_address that is already in use. 


Not applicable on ATM sockets. 


Total per-socket buffer space 
reserved for sends. This is 
unrelated to 
SO_MAX_MSG_SIZE or the 
size of a TCP window. 


Type of socket (for example, 
SOCK_STREAM). 


An opaque data structure object 
from the service provider 
associated with socket s. This 
object stores the current 
configuration information of the 
service provider. The exact 
format of this data structure is 
service provider-specific. 


. Default 


FALSE 


1 is on (default), 
O is off 


Implementation 
dependent 


FALSE 


Protocol 
dependent 


Implementation 
dependent 


FALSE. 


Implementation 
dependent 


As created with 
socket 
Implementation 
dependent 


Calling WSPGetSockOpt with an unsupported option will result | in an error code of 
WSAENOPROTOOPT being returned in /pErrno. 
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SO_DEBUG 
Windows Sockets service providers are encouraged (but not required) to supply 
output debug information if the SO_DEBUG option is set by a Windows Sockets SPI 
client. The mechanism for generating the debug information and the form it takes are 
beyond the scope of this specification. | 


SO_ERROR 
The SO_ERROR option returns and resets the per-socket-based error code (that is 
not necessarily the same as the per-thread-error code that is maintained by the 
~Ws2_32.dll). A successful Windows Sockets call on the socket does not reset the 
socket-based error code returned by the SO_ERROR option. 


SO GROUP_ID 
Reserved. This value should be NULL. 


SO_GROUP_PRIORITY 
Reserved. 
SO_KEEPALIVE 
A Windows Sockets SPI client can request that a TCP/IP service provider enable the 
use of keep-alive packets on TCP-connections by turning on the SO_KEEPALIVE 
socket option. A Windows Sockets provider need not support the use of keep-alives: if 
it does, the precise semantics are implementation specific but should conform to 
section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts—Communication 
Layers. lf a connection is dropped as the result of keep-alives, the error code 
WSAENETRESET is returned to any calls in progress on the socket, and any 
subsequent calls will fail win WSAENOTCONN. 


SO_LINGER 
~SO_LINGER controls the action taken when unsent data is queued on a socket and a 
WSPCloseSocket is performed. See WSPCloseSocket for a description of the way 
in which the SO_LINGER settings affect the semantics of WSPCloseSocket. The 
Windows Sockets SPI client obtains the desired behavior by creating a LINGER 
structure (pointed to by the optval argument) with the following elements: 


SO_ MAX_MSG_SIZE 
This is a get-only socket option, which indicates the maximum size of an outbound 
send message for message-oriented socket types (for example, SOCK_DGRAM) as 
implemented by the service provider. It has no meaning for byte stream-oriented 
sockets. There is no provision to determine the maximum inbound message size. 

SO PROTOCOL_INFOW ~~ 
This is a get-only option that supplies the WSAPROTOCOL_ INFO structure 
associated with this socket. See WSCEnumProtocols for more information about this 
structure. 
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SO_SNDBUF | 
When a Windows Sockets service provider supports the SO. RCVBUF and 
SO_SNDBUF options, a Windows Sockets SPI client can use WSPSetSockOpt to 
request different buffer sizes (larger or smaller). The call can succeed even though 
the service provider did not make available the entire amount requested. A Windows 
Sockets SPI client must call this function with the same option to check the buffer size 
actually provided. 


SO_REUSEADDR > 

By default, a socket can not be bound (see WSPBind) to a local address that is 
already in use. On occasion, however, it may be desirable to reuse an address in this 
way. Since every connection is uniquely identified by the combination of local and 
remote addresses, there is no problem with having two sockets bound to the same 
local address as long as the remote addresses are different. To inform the Windows 
Sockets provider that a WSPBind on a socket should be allowed to bind to a local 
address that is already in use by another socket, the Windows Sockets SPI client 
should set the SO_REUSEADDR socket option for the socket before issuing the 

~ WSPBind. Note that the option is interpreted only at the time of the WSPBind.. It is 
therefore unnecessary (but harmless) to set the option on a socket that is not to be 
bound to an existing address, and setting or resetting the option after the WSPBind 
has no effect on this or any other socket. 


PVD_CONFIG 
This option retrieves an opaque data structure object from the service provider 
associated with socket s. This object stores the current configuration information of 
the service provider. The exact format of this data structure is service-provider 
specific. | 


Error Codes 

Error code _ Meaning 

WSAENETDOWN Network subsystem has failed. 

WSAEFAULT One of the optval or the optlen arguments is not a valid part of 
| the user address space, or the optlen argument is too small. 

WSAEINVAL The /evel is unknown or invalid. 


WSAEINPROGRESS _ Function is invoked when a callback is in progress. 

WSAENOPROTOOPT _ Option is unknown or unsupported by the indicated protocol 
| family. 

WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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WSPSetSockOpt, WSPSocket 


WSPloct 


The WSPloctl function controls the mode of a socket. 


ee 


Parameters 


S 


in] Handle to a socket 


dwloControlCode 


| 


ion to perform 


in] Control code of the operat 
ffer 


IpvinBu 


input buffer 


in] Address of 


cb/inBuffer 
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loThreadld 
[in] Pointer to a WSATHREADID structure to be used by the siieiieel in a subsequent 
call to WPUQueueApc. The provider should store the referenced WSATHREADID 
~ structure (not the pointer to same) until after the WPUQueueApc function returns. 
lpErrno 
[out] Pointer to the error code. 


Remarks 

This routine is used to set or retrieve operating parameters associated with the socket, 
the transport protocol, or the communications subsystem. If both /oOverlapped and 
loCompletionRoutine are NULL, the socket in this function will be treated as a 
nonoverlapped socket. 


For nonoverlapped sockets, /oOverlapped and |poCompletionRoutine parameters are 


_ ignored and this function can block if socket s is in blocking mode. Note that if socket s is 


in nonblocking mode, this function can return WSAEWOULDBLOCK if the specified 
operation cannot be finished immediately. In this case, the Windows Sockets SPI client 
may change the socket to blocking mode and reissue the request or wait for the 
corresponding network event (such as FD_ROUTING_INTERFACE_CHANGE or 
FD_ADDRESS_LIST_CHANGE in case of SIO_LROUTING_INTERFACE_CHANGE or 
SIO_ADDRESS_LIST_CHANGE) using Windows message (through WSPAsyncSelect 
or event (using WSPEventSelect) based notification mechanism. For overlapped 
sockets, operations that cannot be completed immediately will be initiated and 
completion will be indicated at a later time. Final completion status is retrieved through 
WSPGetOverlappedResult. 


Any IOCTL may block indefinitely, depending on the implementation of the service 
provider. If the Windows Sockets SPI client cannot tolerate blocking in a WSPlocti call, 
overlapped I/O would be advised for ioctls that are most likely to block including: 

e SIO_FINDROUTE 

e SIO_FLUSH 

e SIO_GET_QOS 

e SIO_GET_GROUP_QOS 

e SIO_SET_QOS 

e SIO_SET_GROUP_QOS 

e SIO_ROUTING_INTERFACE_CHANGE 

e SIO_ADDRESS_LIST_CHANGE 


Some protocol-specific ioctls may also be particularly likely to block. Check the relevant 
protocol-specific annex for available information. 


In as much as the dwloControlCode parameter is now a 32-bit entity, it is 5 sible to 
adopt an encoding scheme that provides a convenient way to partition the opcode 
identifier space. The dw/loControlCode parameter is constructed to allow for protocol and 
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vendor independence when adding new control codes, while retaining backward 
compatibility with Windows Sockets 1.1 and Unix control codes. The dwloControlCode 
parameter has the following form. | 


I O V T Vendor/address family Code 


3 3. 2 22 22222221111 111:1-11 
1 0 9 87 65432109876 59432109876543210 


| Set if the input buffer is valid for the code, as with lOC_IN. 


O Set if the output buffer is valid for the code, as with IOC_OUT. Note that for codes 
with both input and output parameters, both | and O will be set. 


V Set if there are no parameters for the code, as with IOC_VOID. 
T A two-bit quantity that defines the type of IOCTL. The following values are defined: 
0 The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO. 


1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes 
defined for Windows Sockets 2 will have T == 


2 The IOCTL applies only to a specific address family. 


3 The IOCTL applies only to a specific vendor's provider. This type allows companies 
to be assigned a vendor number that appears in the Vendor/AddressFamily 
member. Then, the vendor can define new ioctls specific to that vendor without 
having to register the IOCTL with a clearinghouse, thereby providing vendor 
flexibility and privacy. 


~The Vendor/Address Family is an 11-bit quantity that defines the vendor who owns the 
code (if T == 3) or that contains the address family to which the code applies (if T == 2). 
If this is a Unix IOCTL code (T == 0) then this member has the same value as the code 
on Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this member can be 
used as an extension of the code member to provide additional code values. 


Code The specific IOCTL code for the operation. 


The following Unix commands are supported. 


Parameters 

FIONBIO 
Enables or disables nonblocking mode on socket s. IpvinBuffer points at an unsigned 
long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be 
disabled. When a socket is created, it operates in blocking mode et is, Menplocking 
mode is disabled). This is consistent with BSD sockets. | 


The wSPAsyncSelect or WSPEventSelect routine automatically sets a socket to 
nonblocking mode. If WSPAsyncSelect or WSPEventSelect has been issued on a 
socket, then any attempt to use WSPloctl to set the socket back to blocking mode will 
fail with WSAEINVAL. To set the socket back to blocking mode, a Windows Sockets 
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_ SPI client must first disable WSPAsyncSelect by calling WSPAsyncSelect with the 
/Event parameter equal to zero, or disable WSPEventSelect by calling 
WSPEventSelect with the /NetworkEvents parameter equal to zero. 


FIONREAD | | 
Determines the amount of data that can be read atomically from socket s. 
lovOutBuffer points at an unsigned long in which WSPloctl stores the result. If sis 
stream oriented (for example, tyoe SOCK_STREAM), FIONREAD returns the total 
amount of data that can be read in a single receive operation; this is normally the 
same as the total amount of data queued on the socket. If s is message oriented (for 
example, type SOCK_DGRAM), FIONREAD returns the size of the first datagram 
(message) queued on the socket. 


SIOCATMARK 
Determines whether or not all OOB data has been read. This applies only to a socket 
of stream style (for example, type SOCK_STREAM) that has been configured for 
inline reception of any OOB data (SO_OOBINLINE). If no OOB data is waiting to be 
read, the operation returns TRUE. Otherwise, it returns FALSE, and the next receive 
operation performed on the socket will retrieve some or all of the data preceding the 
mark; the Windows Sockets SPI client should use the SSOCATMARK operation to 
determine whether any remains. If there is any normal data preceding the urgent 
(OOB) data, it will be received in order. (Note that receive operations will never mix 
OOB and normal data in the same call.) JovOutBuffer points at a BOOL in which 
WSPloctl stores the result. 


The following Windows Sockets 2 commands are supported. 


Parameters 
SIO_ASSOCIATE_HANDLE (opcode setting: |, T==1) 
Associates this socket with the specified handle of a companion interface. The input 
buffer contains the integer value corresponding to the manifest constant for the 
companion interface (for example, TH_NETDEV and TH_TAPI), followed by a value 
that is a handle of the specified companion interface, along with any other required 
information. Refer to the appropriate section in the Windows Sockets 2 Protocol- 
Specific Annex and/or documentation for the particular companion interface for 
additional details. The total size is reflected inthe input buffer length. No output buffer 
is required. The WSAENOPROTOOPT error code is indicated for service providers 
_ that do not support this IOCTL. The handle associated by this IOCTL can be retrieved 
using SIO_TRANSLATE_HANDLE. 


A companion interface might be used, for example, if a particular Rpvicoe provides: 
e A great deal of additional control over the behavior of a socket. 


e Provider-specific controls that do not map to existing Windows Socket functions (or 
those likely for the future). 
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It is recommended that the Component Object Model (COM) be used instead of this 
IOCTL to discover and track other interfaces that might be supported by a socket. 
This lOCTL is present for backward compatibility with systems where COM is not 
available or cannot be used for some other reason. 


SIO_ENABLE_CIRCULAR_QUEUEING (opcode setting: V, T==1) 
Indicates to a message-oriented service provider that a newly arrived message should 
never be dropped because of a buffer queue overflow. Instead, the oldest message in 
the queue should be eliminated in order to accommodate the newly arrived message. 
No input and output buffers are required. Note that this IOCTL is only valid for sockets 
associated with unreliable, message-oriented protocols. The WSAENOPROTOOPT 
error code is indicated for service providers that do not support this IOCTL. 
SIO_FIND_ROUTE (opcode setting: O, T==1) 
When issued, this IOCTL requests that the route to the remote address specified as a 
SOCKADDR in the input buffer be discovered. If the address already exists in the 
local cache, its entry is invalidated. In the case of Novell’s IPX, this call initiates an 
IPX GetLocalTarget (GLT), that queries the network for the given remote address. 


SIO_FLUSH (opcode setting: V, T==1) | 
Discards current contents of the sending queue associated with this socket. No input 
and output buffers are required. The WSAENOPROTOOPT error code is indicated for 
service providers that do not support this IOCTL. 


SIO_GET_BROADCAST_ADDRESS (opcode setting: O, T==1) 
This IOCTL fills the output buffer with a SOCKADDR structure containing a suitable 
broadcast address for use with WSPSendTo. 


SIO_GET_EXTENSION FUNCTION POINTER (opcode setting: O, |, T==1) 
Retrieves a pointer to the specified extension function supported by the associated 
service provider. The input buffer contains a GUID whose value identifies the 
extension function in question. The pointer to the desired function is returned in the 
output buffer. Extension function identifiers are established by service provider 
vendors and should be included in vendor documentation that describes extension 
function capabilities and semantics. 


SIO_GET_QOS (opcode setting: O, T==1) 
Retrieves the QOS structure associated with the socket. The input buffer is optional. 
Some protocols (for example, RSVP) allow the input buffer to be used to qualify a 
QOS request. The QOS structure will be copied into the output buffer. The output 
buffer must be sized large enough to be able to contain the full QOS structure. The 
WSAENOPROTOOPT error code is indicated for service pe ae that do not support 

_ quality of service. 

SIO_GET_GROUP_QOS (opcode setting: O, T= 1) 
Reserved. 

SIO_MULTIPOINT_LOOPBACK (opcode setting: |, 74) | 
Controls whether data sent in a multipoint session will also be received by the same 
socket on the local host. A value of TRUE causes loopback reception to occur while a 
value of FALSE =sproniots this. 
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SIO_MULTICAST_SCOPE (opcode setting: |, T==1) _ 3 
Specifies the scope over which multicast transmissions will occur. Scope is defined as 
the number of routed network segments to be covered. A scope of zero would 
indicate that the multicast transmission would not be placed on the wire, but could be 
disseminated across sockets within the local host. A scope value of 1 (the default) 
indicates that the transmission will be placed on the wire, but will not cross any 
routers. Higher scope values determine the number of routers that can be crossed. 
Note that this corresponds to the time-to-live (TTL) parameter in IP multicasting. 
SIO_SET_QOS (opcode setting: |, T==1) 
Associate the supplied QOS structure with the socket. No output buffer is required, 
the QOS structure will be obtained from the input buffer. The WSAENOPROTOOPT 
error code is indicated for service providers that do not support quality of service. 
SIO_SET_GROUP_QOS (opcode setting: |, T==1) 
Reserved. 


SIO_TRANSLATE_HANDLE (opcode setting: |, O, T==1) 
To obtain a corresponding handle for socket s that is valid in the context of a 
companion interface (for example, TH_NETDEV and TH_TAPI). A manifest constant 
identifying the companion interface along with any other needed parameters are 
specified in the input buffer. The corresponding handle will be available in the output 
buffer upon completion of this function. Refer to the appropriate section in the 
Windows Sockets 2 Protocol-Specific Annex and/or documentation for the 
particular companion interface for additional details. The WSAENOPROTOOPT error 
code is indicated for service providers that do not support this IOCTL for the specified 
companion interface. This IOCTL retrieves the handle associated using 
SIO_TRANSLATE_HANDLE. 


It is recommended that COM be used instead of this IOCTL to discover and track 
other interfaces that might be supported by a socket. This IOCTL is present for 
backward compatibility with systems where COM is not available or cannot be used 
for some other reason. 


SIO_ROUTING_INTERFACE_QUERY Bead setting: |, O, T==1) 
To obtain the address of the local interface (represented as SOCKADDR structure) 
that should be used to send to the remote address specified in the input buffer (as 
SOCKADDR). Remote multicast addresses may be submitted in the input buffer to 
get the address of the preferred interface for multicast transmission. In any case, the 
interface address returned may be used by the application ina pupPemer bind 
request. 


Note that routes are subject to change. Therefore, Windows Socket SPI clients cannot 
rely on the information returned by SIO_ROUTING_INTERFACE_QUERY to be 
persistent. SPI clients may register for routing change notifications using the 
SIO_ROUTING_INTERFACE_CHANGE IOCTL, which provides for notification 
through either overlapped I/O or a FD_ROUTING_INTERFACE_CHANGE event. The 
following sequence of actions can be used to guarantee that the Windows Socket SPI 
client always has current routing interface information for a given destination. 
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e Issue SIO_ROUTING_INTERFACE_CHANGE IOCTL. 
e Issue SIO_ROUTING_INTERFACE_QUERY IOCTL. 


e Whenever SIO_ROUTING_INTERFACE_CHANGE IOCTL notifies the WinSock 
SPI client of routing change (either through overlapped |/O or by signaling 
FD_ROUTING_INTERFACE_CHANGE event), the whole sequence of actions 
should be repeated. 


If output buffer is not large enough to contain the interface address, 
SOCKET_ERROR is returned as the result of this IOCTL and WSPGetLastError 
returns WSAEFAULT. The required size of the output buffer will be returned in 

_ IpcbBytesReturned in this case. Note the WSAEFAULT error code is also returned if 
the JovinBuffer, |ovOutBuffer, or |pcbBytesReturned parameter is not totally contained 
in a valid part of the user address space. 


If the destination address specified in the input buffer cannot be reached through any 
of the available interfaces, SOCKET_ERROR is returned as the result of this IOCTL 
and WSAGetLastError returns WSAENETUNREACH or even WSAENETDOWN if all 
of the network connectivity is lost. 
SIO_ROUTING_INTERFACE_CHANGE (opcode setting: |, T==1) 
To receive notification of the interface change that should be used to reach the 
remote address in the input buffer (specified as a SOCKADDR structure). No output 
information will be provided upon completion of this IOCTL; the completion merely 
indicates that the routing interface for a given destination has changed and should be 
queried again through SIO_ ROUTING_INTERFACE_QUERY. 


It is assumed (although not required) that the Windows Socket SPI client uses 

_ overlapped I/O to be notified of routing interface change through completion of 
SIO_ROUTING_INTERFACE_CHANGE request. Alternatively, if the 

~ SIO_ROUTING_INTERFACE_CHANGE IOCTL is issued on a nonblocking socket 

and without overlapped parameters (/oOverlapped / CompletionRoutine are set to 
NULL), it will complete immediately with error WSAEWOULDBLOCK andthe 
Windows Socket SPI client can then wait for routing change events using a call to 

-~WSPEventSelect or WSPAsyncSelect with the 
FD_ROUTING_INTERFACE_CHANGE bit set in the network event bitmask. 


_ It is recognized that routing information remains stable in most cases. So requiring the 
Windows Sockets SPI client to keep multiple outstanding |OCTLs—for notifications 
about all destinations that it is interested in as well as having the service provider 
keep track of all the m—will unnecessarily tie up significant system resources. This 
situation can be avoided by extending the meaning of the input parameters and 
relaxing the service provider requirements as follows: _ 


~ The Windows Sockets SPI client can specify a protocol family specific wildcard 
address (same as one used in bind call when requesting to bind to any available 
address) to request notifications of any routing changes. This allows the Windows 
Sockets SPI client to keep only one outstanding 3 
~SIO_ROUTING_INTERFACE_CHANGE for all the sockets/destinations it has and 
then use SIO_ROUTING_INTERFACE_QUERY to get the actual routing -* 
information. : 
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Service provider can opt to ignore the information supplied by the Windows 
Sockets SPI client in the input buffer of the 
SIO_ROUTING_INTERFACE_CHANGE (as though the Windows Sockets SPI 
client specified a wildcard address) and complete the 
SIO_ROUTING_INTERFACE_CHANGE IOCTL or signal 
FD_ROUTING_INTERFACE_CHANGE event in the event of any routing 
information change (not just the route to the destination specified in the input 
buffer). 


SIO_ADDRESS_LIST_QUERY (opcode setting: |, O, T== 

To obtain a list of local transport addresses of the socket’s protocol family to which the 
Windows Sockets SPI client can bind. The list returned in the output buffer using the 
following format: 


Note that in Win32 Plug and Play environments, addresses can be added and 
removed dynamically. Therefore, Windows Sockets SPI clients cannot rely on the 
information returned by SIO_ADDRESS_LIST_QUERY ito be persistent. Windows 
Sockets SPI clients may register for address change notifications through the 
SiIO_ADDRESS_LIST_CHANGE IOCTL that provides for notification through either 
overlapped I/O or FD_ADDRESS_LIST_CHANGE event. The following sequence of 
actions can be used to guarantee that the Windows Sockets SPI client always has 
current address list information: 


e Issue SIO_ADDRESS_LIST_CHANGE IOCTL. 
e Issue SIO_ADDRESS_LIST_QUERY IOCTL. 


e Whenever SIO_ADDRESS_LIST_CHANGE IOCTL notifies the Windows Sockets 
SPI client of address list change (either through overlapped I/O or by signaling 
FD_ADDRESS_LIST_CHANGE event), the whole sequence of actions should be 
repeated. 


If the output buffer is not large enough to contain the address list, SOCKET_ERROR 
is returned as the result of this IOCTL and WSPGetLastError returns WSAEFAULT. 
The required size of the output buffer will be returned in jocbBytesReturned in this 
case. Note the WSAEFAULT error code is also returned if the /pvinBuffer, 
lpvOutBuffer, or lpcbBytesReturned parameter is not totally contained ina valid part of 
the user address space. 


SIO_ADDRESS_LIST_CHANGE (opcode setting: T== 


To receive notification of changes in the list of local transport addresses of the 
socket's protocol family to which the Windows Sockets SPI client can bind. No output 
information will be provided upon completion of this IOCTL; the completion merely 
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indicates that the list of available local addresses has changed and should be queried 
again through SIO_ADDRESS_LIST_QUERY. 


It is assumed (although not required) that the Windows Sockets SPI client uses 
overlapped I/O to be notified of change by completion of 
SIO_ADDRESS_LIST_CHANGE request. Alternatively, if the 
SIO_ADDRESS_LIST_CHANGE IOCTL is issued on a nonblocking socket and 
without overlapped parameters (/oOverlapped and |pCompletionRoutine are set to 
NULL), it will complete immediately with error WSAEWOULDBLOCK. The Windows 
Sockets SPI client can then wait for address list change events through a call to 
WSPEventSelect or WSPAsyncSelect with the FD _ADDRESS_LIST_CHANGE bit 
set in the network event bitmask. 


SIO_QUERY_PNP_TARGET_HANDLE (opcode setting: O, T==1) 

To obtain the socket descriptor of the next provider in the chain on which the current 
_socket depends in PnP sense. This IOCTL is invoked by the Windows Sockets 2 DLL 
_only on sockets of non-IFS service providers created through 

WPUCreateSocketHandle call. The provider should return in the output buffer the 

socket handle of the next provider in the chain on which a given socket handle 

depends in PnP sense (for example, the removal of the device that supports the 
underlying handle will result in the invalidation of the handle above it in the chain). 


If an overlapped operation completes immediately, this function returns a value of 
zero and the IocbBytesReturned parameter is updated with the number of bytes in the 
output buffer. If the overlapped operation is successfully initiated and will complete 
later, this function returns SOCKET_ERROR and indicates error code 
WSA_IO_PENDING. In this case, /pcbBytesReturned is not updated. When the 
overlapped operation completes, the amount of data in the output buffer is indicated 
either through the cbTransferred parameter in the completion routine (if specified), or 
through the /pcbTransfer parameter in WSPGetOverlappedResult. 


When called with an overlapped socket, the lpOverlapped parameter must be valid for. 
the duration of the overlapped cone The WSAOVERLAPPED structure has the 
following form: 


If the joCompletionRoutine parameter is NULL, the service provider signals the hEvent 
member of /pOverlapped when the overlapped operation completes if it contains a valid 
event object handle. The Windows Sockets SPI client can use 
WSPGetOverlappedResult to poll or wait on the event object. 
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lf JoCompletionRoutine is not NULL, the hEvent member is ignored and can be used by 
the Windows Sockets SPI client to pass context information to the completion routine. A 
client that passes a non-NULL /pCompletionRoutine and later calls 
WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait 
parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case, the 
usage of the hEvent member is undefined, and attempting to wait on the hEvent 
member would produce unpredictable results. 


It is the service provider's responsibility to arrange for invocation of the client specified— 
completion routine when the overlapped operation completes. Since the completion 
routine must be executed in the context of the same thread that initiated the overlapped 
operation, it cannot be invoked directly from the service provider. The Ws2_32.dll offers 
an asynchronous procedure call (APC) mechanism to facilitate invocation of completion 
routines. 


A service provider arranges for a function to be executed in the proper thread and 
process context by calling WPUQueueApc. This function can be called from any 
process and thread context, even a context different from the thread and process that 
was used to initiate the overlapped operation. 


WPUQueueApc takes as input parameters a pointer to a WSATHREADID structure 
(supplied to the provider through the /oThreadld input parameter), a pointer to an APC 
function to be invoked, and a 32-bit context value that is subsequently passed to the 
APC function. Because only a single 32-bit context value is available, the APC function 
itself cannot be the client specified—completion routine. The service provider must 
instead supply a pointer to its own APC function that uses the supplied context value to 
access the needed result information for the overlapped operation, and then invokes the 
client specified—completion routine. 


The prototype for the client-supplied completion routine is as follows: 


CompletionRoutine is a placeholder for a client supplied function. The dwError 
specifies the completion status for the overlapped operation as indicated by 
lpOverlapped. The cbTransferred specifies the number of bytes returned. Currently, 
there are no flag values defined and dwFlags will be zero. This function does not return 
a value. 


Returning from this function allows invocation of another pending completion routine for 
this socket. The completion routines can be called in any order, though not necessarily | in 
the same order that the overlapped operations are completed. 
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Compatibility 


The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley 
sockets. In particular, there is no command that is equivalent to FIOASYNC. 


Return Values 

If no error occurs and the operation has completed immediately, WSPloctl returns zero. 
Note that in this case the completion routine, if specified, will have already been queued. 
Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is 
available in /pErrno. The error code WSA_IO_PENDING indicates that an overlapped 
operation has been successfully initiated and that completion will be indicated at a later 
time. Any other error code indicates that no overlapped operation was initiated and no 
completion indication will occur. — 


Error Codes | 


Error code Meaning 
WSAENETDOWN Network subsystem has failed. | 
WSAEFAULT The /pvinBuffer, |pvOutBuffer or Ip>cbBytesReturned argument 


is not totally contained in a valid part of the user address 
space, or the cb/nBuffer or cbOutBuffer argument is too small. 


WSAEINVAL The dwloControlCode is not a valid command, or a supplied 
_ input parameter is not acceptable, or the command is not | 
applicable to the type of socket supplied. 


| WSAEINPROGRESS Function is invoked when a callback is in progress. | 
WSAENOTSOCK Descriptor s is not a socket. | 


WSAEOPNOTSUPP Specified IOCTL command cannot be realized. For example, 
the flow specifications specified i in SIO_SET_QOS cannot be 
| satisfied. 
WSA_IO_PENDING An overlapped operation was successfully initiated and 
~ completion will be indicated at a later time. 


WSAEWOULDBLOCK _ Socket is marked as nonblocking and the requested operation 
| would block. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSocket, WSPSetSockOpt, WSPGetSockOpt, WPUQueueApc 
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WSPJoinLeaf | 


The WSPVJoinLeaf function joins a leaf node into a multipoint session, exchanges 
connect data, and specifies needed quality of service based on the supplied flow 
specifications. 


Parameters 
Ss 
[in] Descriptor identifying a multipoint socket. 


name | 
[in] Name of the peer to which the socket is to be joined. 


namelen 
[in] Length of the name. 


IpCallerData | 
[in] Pointer to the user data that is to be transferred to the peer during multipoin 
session establishment. 


lpCalleeData 
[out] Pointer to the user data that is to be transferred back from the peer during 
multipoint session establishment. 


IpSQOS | 
[in] Pointer to the flow specifications for socket s, one for each direction. 


IpDGQOS 
[in] Reserved. 


dwFlags | 3 
in] Flags to indicate that the socket is acting as a sender, receiver, or both. 


lpErrno | 
out] Pointer to the error code. 
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Return Values : 

If no error occurs, WSPJoinLeaf returns a value of tyoe SOCKET that is a descriptor for 
the newly created multipoint socket. Otherwise, a value of INVALID_SOCKET is 
returned, and a specific error code is available in /oErrno. 


On a blocking socket, the return value indicates success or failure of the join operation. 


With a nonblocking socket, successful initiation of a join operation is indicated by a 
return value of a valid socket descriptor. Subsequently, an FD_CONNECT indication is 
given when the join operation completes, either successfully or otherwise. The error 

_ code associated with the FD_CONNECT indicates the success or failure of the 
WSPJoinLeaf. 


Also, until the multipoint session join attempt completes all subsequent calls to 
WSPJoinLeaf on the same socket will fail with the error code WSAEALREADY. After 
the WSAJoinLeaf completes successfully a subsequent attempt will usually fail with the 
error code WSAEISCONN. An exception to the WSAEISCONN rule occurs for a c_root 
socket that allows root-initiated joins. In such a case another join may be initiated after a 
prior WSAJoinLeaf completes. 


lf the return error code indicates the multipoint session join attempt failed (that is, 
WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the Windows 
Sockets SPI client can call WSPJoinLeaf again for the same socket. 


Remarks — 
This function is used to join a leaf node to a : multipoint session, and to perform a number 
of other ancillary operations that occur at session join time as well. If the socket, s, is 
unbound, unique values are assigned to the local association by the system, and the 
socket is marked as bound. 


WSPJoinLeaf has the same parameters and semantics as WSPConnect except that it 
returns a socket descriptor (as in WSPAccept), and it has an additional dwFlags 
parameter. Only multipoint sockets created using WSPSocket with appropriate 
multipoint flags set can be used for input parameter s in this function. If the socket is in 
the nonblocking mode, the returned socket descriptor will not be useable until after a 
corresponding FD_CONNECT indication on the original socket s has been received, 
except that closesocket can be invoked on this new socket descriptor to cancel a 
pending join operation. A root node in a multipoint session can call WSPJoinLeaf one or 
more times in order to add a number of leaf nodes, however at most one multipoint 
connection request can be outstanding at a time. Refer to Protocol-Independent 
Multicast and Multipoint in the SPI for additional information. 


For nonblocking sockets it is often not possible to complete the connection immediately. 
In such a case, this function returns an as-yet unusable socket descriptor and the 
operation proceeds. There is no error code such as WSAEWOULDBLOCK in this case, 
since the function has effectively returned a “successful start” indication. When the final 
outcome success or failure becomes known, it may be reported through 
WSPAsyncSelect or WSPEventSelect depending on how the client registers for 
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notification on the original socket s. In either case, the notification is announced with 
FD_CONNECT and the error code associated with the FD_CONNECT indicates either 
success or a specific reason for failure. Note that WSPSelect cannot be used to detect 
completion notification for WSAJoinLeaf. 


The socket descriptor returned by WSPJoinLeaf is different depending on whether the 
input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the 
name parameter designates a particular leaf node to be added and the returned socket 
descriptor is a c_leaf socket corresponding to the newly added leaf node. (As is 
described in section Descriptor Allocation, wnen new socket descriptors are allocated 
IFS providers must call WPUModifylFSHandle and non-iFS providers must call 
WPUCreateSocketHandle). The newly created socket has the same properties as s 
including asynchronous events registered with WSPAsyncSelect or with 
WSPEventSelect. It is not intended to be used for exchange of multipoint data, but 
rather is used to receive network event indications (for example, FD_CLOSE) for the 
connection that exists to the particular c_leaf. Some multipoint implementations can also 
allow this socket to be used for “side chats” between the root and an individual leaf 
node. An FD_CLOSE indication will be received for this socket if the corresponding leaf 
node calls WSPCloseSocket to drop out of the multipoint session. Symmetrically, 
invoking WSPCloseSocket on the c_leaf socket returned from WSPUJoinLeaf will cause 
the socket in the corresponding leaf node to get FD_CLOSE notification. 


When WSPuJoinLeaf is invoked with a c_leaf socket, the name parameter contains the 
address of the root node (for a rooted control scheme) or an existing multipoint session 
(nonrooted control scheme), and the returned socket descriptor is the same as the input 
socket descriptor. In other words, a new socket descriptor is not allocated. In a rooted 
control scheme, the root application would put its c_root socket in the listening mode by 
calling WSPListen. The standard FD_ACCEPT notification will be delivered when the 
leaf node requests to join itself to the multipoint session. The root application uses the 
usual WSPAccept functions to admit the new leaf node. The value returned from 
WSPAccept is also a c_leaf socket descriptor just like those returned from 
WSPJoinLeaf. To accommodate multipoint schemes that allow both root-initiated and 
leaf-initiated joins, it is acceptable for a c_root socket that is already in listening mode to 
be used as an input to WSPJoinLeaf. 


The Windows Sockets SPI client is responsible for allocating any memory space pointed 
to directly or indirectly by any of the parameters it specifies. | 


The /pCallerData is a value parameter that contains any user data that is to be sent 
along with the multipoint session join request. If /oCa/lerData is NULL, no user data will | 
be passed to the peer. The /pCalleeData is a result parameter that will contain any user 
data passed back from the peer as part of the multipoint session establishment. — 
lpCalleeData->len initially contains the length of the buffer allocated by the Windows 
Sockets SPI client and pointed to by /oCalleeData->buf. |pCalleeData->len will be set to 
zero if no user data has been passed back. The /pCa/lleeData information will be valid 
when the multipoint join operation is complete. For blocking sockets, this will be when 
the WSPJoinLeaf function returns. For nonblocking sockets, this will be after the 
FD_CONNECT notification has occurred on the original socket s. If joCalleeData is 
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NULL, no user data will be passed back. The exact format of the user data is specific to 
the address family to which the socket belongs and/or the applications involved. 


At multipoint session establishment time, a Windows Sockets SPI client can use the 
IDSQOS parameters to override any previous QOS specification made for the socket 
through WSPloctl with the SIO_SET_QOS opcode. : 


IDSQOS specifies the flow specifications for socket s, one for each direction, followed by 
any additional provider-specific parameters. If either the associated transport provider in 
general or the specific type of socket in particular cannot honor the QOS request, an 
error will be returned as indicated below. The sending or receiving flow specification 
values will be ignored, respectively, for any unidirectional sockets. If no provider-specific 
parameters are supplied, the buf and Jen members of |OSQOS->ProviderSpecific should 
be set to NULL and zero, respectively. A NULL value for jJoOSQOS indicates no 
application supplied quality of service. 


The dwFlags parameter is used to indicate whether the socket will be acting only asa 
sender (JL_SENDER_ONLY), only as a receiver (JL_RECEIVER -ONLY), or ou 
(JL_BOTH). 


_ Note When connected sockets break (that is, become closed for whatever reason), 
they should be discarded and recreated. It is safest to assume that when things go awry 
for any reason on a connected socket, the Windows Sockets SPI client must discard and 
recreate the needed sockets in order to return to a stable point. 


Error Codes 


Error code . Meaning 
WSAENETDOWN Network subsystem has failed. 
WSAEADDRINUSE Socket’s local address is already in use and the socket 
a was not marked to allow address reuse with 
SO_REUSEADDR. This error usually occurs at the time 
of bind, but could be delayed until this function if the | 
bind was to a partially wild-card address (involving 
ADDR_ANY) and if a specific address needs to be 
| “committed” at the time of this function. © 
WSAEINTR (Blocking) call was canceled through 
a | _ WSPCancelBlockingCall. a 
_ WSAEINPROGRESS Blocking Windows Sockets call is in progress, or the 
ae : Service provider is still processing a callback function. 
~ WSAEALREADY © ~ Nonblocking WSPJoinLeaf call is in progress on the 
. } specified socket. 
| WSAEADDRNOTAVAIL Remote address is not a valid address (for example, 
| : a ADDR ANY). | 


continued 
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(continued) 

Error code Meaning 

WSAEAFNOSUPPORT Addresses in the specified family cannot be used with 
this socket. 

WSAECONNREFUSED The attempt to join was forcefully rejected. 

WSAEFAULT Name or the namelen argument is not a valid part of the 
user address space, the namelen argument is too 
small, the buffer length for joCalleeData, |pDSQOS, and 
IpGQOS are too small, or the buffer length for 
|pCallerData is too large. 

WSAEISCONN Socket is already member of the multipoint session. 

WSAENETUNREACH Network cannot be reached from this host at this time. 

WSAENOBUFS No buffer space is available. The socket cannot be 
joined. 

WSAENOTSOCK Descriptor is not a socket. 

WSAEOPNOTSUPP Flow specifications specified in IpSQOS cannot be 
satisfied. 

WSAEPROTONOSUPPORT __ The /pCallerData augment is not supported by the 
service provider. 

WSAETIMEDOUT Attempt to join timed out without establishing a 


multipoint session. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


oe 


WSPBind, WSPSelect, WSPAccept, WSPAsyncSelect, WSPEventSelect, 


WSPSocket 


~WSPListen 


The WSPListen function establishes a socket to listen for incoming connections. 
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Parameters 


S 
[in] Descriptor identifying a bound, unconnected socket. 


backlog 
[in] Maximum length to which the queue of pending connections can grow. If this 
value is SOMAXCONN, then the service provider should set the backlog to a 
maximum “reasonable” value. There is no standard provision to find out the actual 
backlog value. | | 


lpErrno 
[out] Pointer to the error code. 


Return Values 
If no error occurs, WSPListen returns zero. Otherwise, a value of SOCKET_ERROR is 
returned, and a specific error code is available in /oErrno. 


Remarks 7 

To accept connections, a socket is first created with WSPSocket bound to a local 
address with WSPBind, a backlog for incoming connections is specified with 
WSPListen, and then the connections are accepted with WSPAccept. WSPListen 
applies only to sockets that are connection oriented (for example, SOCK_STREAM). 
The socket s is put into passive mode where incoming connection requests are 
acknowledged and queued pending acceptance by the Windows Sockets SPI client. 


This function is typically used by servers that could have more than one connection 
request at a time: if a connection request arrives with the queue full, the client will 
receive an error with an indication of WSGAECONNREFUSED. 


WSP_Listen should continue to function rationally when there are no available 
descriptors. It should accept connections until the queue is.emptied. If descriptors 
become available, a later call to WSPListen or WSPAccept will refill the queue to the 
current or most recent “backlog”, if possible, and resume listening for incoming 
connections. 


A Windows Sockets SPI client can call WSPListen more than once on the same socket. » 
This has the effect of updating the current backlog for the listening socket. Should there 
be more pending connections than the new backlog value, the excess pending | 
connections will be reset end dropped. | 


| Compatibility 

backlog is limited (silently) to a reasonable value as determined by the service provider. 
Illegal values are replaced by the nearest legal value. There i IS no standard provision to 
find out the actual re value. 
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Error Codes 
Errorcode — Meaning — 
WSAENETDOWN Network subsystem has failed. 


WSAEADDRINUSE Socket’s local address is already in use and the socket was 
not marked to allow address reuse with SO_REUSEADDR. 
This error usually occurs at the time of bind, but could be 
delayed until this function if the bind was to a partially wildcard 
address (involving ADDR_ANY) and if a specific address 
needs to be committed at the time of this function. 


WSAEINPROGRESS _ Function is invoked when a callback is in progress. 


WSAEINVAL Socket has not been bound with WSPBind. 

WSAEISCONN Socket is already connected. 

WSAEMFILE No more socket descriptors are available. 

WSAENOBUFS No buffer space is available. 

WSAENOTSOCK Descriptor is not a socket. 

WSAEOPNOTSUPP _ Referenced socket is not of a type that supports the 
WSPListen operation. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPAccept, WSPConnect, WSsPSocket 


WSPRecv 


The WSPRecv function receives data on a socket. 
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Parameters 


S 
[in] Descriptor identifying a connected socket. 


lpBuffers 
[in/out] Pointer to an array of WSABUF structures. Each WSABUF structure contains 
a pointer to a buffer and the length of the buffer. 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesRecvd 

[out] Pointer to the number of bytes received by this call. 
_|IpFlags 
[in/out] Pointer to flags. 


IpOverlapped 
[in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped simiciras): 


lIoCompletionRoutine 
[in] Pointer to the completion routine called when the receive operation has been 
completed (ignored for nonoverlapped structures). 


loThreadid | 
[in] Pointer to a WSATHREADID structure to be used by the provider ina subsequent | 
call to WPUQueueApc. The provider should store the referenced WSATHREADID 
structure (not the pointer to same) until after the WPUQueueApc function returns. 


IpErrno 
[out] Pointer to the error code. 


Return Values 

If no error occurs and the receive operation nas completed immediately, WSPRecv 
returns zero. Note that in this case the completion routine, if specified, will have already 
been queued. Otherwise, a value of SOCKET_ERROR is returned, and a specific error 
code is available in /oErrno. The error code WSA_IO_PENDING indicates that the 
overlapped operation has been successfully initiated and that completion will be 
indicated at a later time. Any other error code indicates that no overlapped operations 
was initiated and no completion indication will occur. | 


Remarks i ne 

WSPRecv is used on connected sockets or bound connectionless sockets specified by — 
the s parameter and is used to read incoming data. The socket’s local address must be 
known. This may be done explicitly through WSPBind or r implicitly through WSPAccept, 
WSPConnect, WSPSendTo, or WSPJoinLeaf. 


For connected, connectionless sockets, this function restricts the addresses from which 
received messages are accepted. The function only returns messages from the remote 
address specified in the connection. ‘Messages from other addresses are (silently) 
discarded. 
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For overlapped sockets WSPRecv is used to post one or more buffers into which 
incoming data will be placed as it becomes available, after which the Windows Sockets 
SPI client-specified completion indication (invocation of the completion routine or setting 
of an event object) occurs. If the operation does not complete immediately, the final 
completion status is retrieved through the completion: routine or 
WSPGetOverlappedResult. 


If both [pOverlapped and IpCompletionRoutine are NULL, the socket in this function will 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the /oOverlapped, IoCompletionRoutine, and loThreadld 
parameters are ignored. Any data that has already been received and buffered by the 
transport will be copied into the supplied user buffers. For the case of a blocking socket 
with no data currently having been received and buffered by the transport, the call will 
block until data is received. Windows Sockets 2 does not define any standard blocking 
timeout mechanism for this function. For protocols acting as byte-stream protocols the 
stack tries to return as much data as possible subject to the supplied buffer space and 
amount of received data available. However, receipt of a single byte is sufficient to 
unblock the caller. There is no guarantee that more than a single byte will be returned. 
For protocols acting as message-oriented, a full message is required to unblock 

the caller. 


Whether or not a protocol is acting as byte-stream is determined by the setting of 
XP1_MESSAGE_ORIENTED and XP1_PSEUDO_STREAM in its 
WSAPROTOCOL_INFO structure and the setting of the MSG_PARTIAL flag passed in 
to this function (for protocols that support it). The relevant combinations are summarized 
in the following table (an asterisk (*) indicates that the setting of this bit does not matter 
in this case). 


XP1_MESSAGE _ XP1_PSEUDO_._ 

ORIENTED STREAM MSG_PARTIAL Acts as 

not set i . | byte-stream 

‘ set : byte-stream 

set not set | set byte-stream 

set not set not set message-oriented 


The supplied buffers are filled in the order in which they appear in the array pointed to by 
lpBuffers, and the buffers are packed so that no holes are created. 


The array of WSABUF structures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider’s 
responsibility to capture this array of pointers to WSABUF structures before returning 
from this call. This enables Windows Sockets SPI clients to build stack- based 
WSABUF arrays. 
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For byte stream-style sockets (for example, type SOCK_STREAM), incoming data is 
placed into the buffers until the buffers are filled, the connection is closed, or internally 
buffered data is exhausted. Regardless of whether or not the incoming data fills all the 
buffers, the completion indication occurs for overlapped sockets. For message-oriented 
sockets (for example, type SOCK_DGRAM), an incoming message is placed into the 
supplied buffers, up to the total size of the buffers supplied, and the completion 
indication occurs for overlapped sockets. If the message is larger than the buffers 
supplied, the buffers are filled with the first part of the message. If the MSG_PARTIAL 
feature is supported by the service provider, the MSG_PARTIAL flag is set in /oflags and 
subsequent receive operation(s) can be used to retrieve the rest of the message. If 
MSG_PARTIAL is not supported but the protocol is reliable, WSPRecv generates the 
error WSAEMSGSIZE and a subsequent receive operation with a larger buffer can be 
used to retrieve the entire message. Otherwise, (that is, the protocol is unreliable and 
does not support MSG_PARTIAL), the excess data is lost, and WSPRecv generates the 
error WSAEMSGSIZE. 


For connection-oriented sockets, WSPRecv can indicate the graceful termination of the 
virtual circuit in one of two ways, depending on whether the socket is a byte stream or 
message oriented. For byte streams, zero bytes having been read indicates graceful 
closure and that no more bytes will ever be read. For message-oriented sockets, where 
a zero byte message is often allowable, a return error code of WSAEDISCON is used to 
indicate graceful closure. In any case a return error code of WSAECONNRESET 
indicates an abortive close has occurred. | 


lpFlags can be used to influence the behavior of the function invocation beyond the © 
options specified for the associated socket. That is, the semantics of this function are 
determined by the socket options and the /pFlags parameter. The latter is constructed by 
using the bitwise OR operator with any of the following values. | : 


Value Meaning 


~ MSG_PEEK | Peeks at the incoming data. The data is copied into the buffer but is 
not removed from the input queue. This flag is valid only for 
nonoverlapped sockets. 


MSG_OOB Processes OOB data (See section. DECnet Out-Of-band data io a 
discussion of this topic.) 


MSG_PARTIAL _ This flag is for message-oriented sockets only. On output, indicates 
that the data supplied is a portion of the message transmitted by the | 
sender. Remaining portions of the message will be supplied in 

subsequent receive operations. A subsequent receive operation with 
MSG_PARTIAL flag cleared indicates end of sender’s message. 


As an input parameter, MSG_PARTIAL indicates that the receive 


operation should complete even if only part ofa message. has been 
received by the service provider. 
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Overlapped Socket I/O 


lf an overlapped operation completes immediately, WSPRecv returns a value of zero 
and the JoNumberOfBytesRecvd parameter is updated with the number of bytes received 
and the flag bits pointed by the /pFlags parameter are also updated. If the overlapped 
operation is successfully initiated and will complete later, WSPRecv returns 
SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
lpoNumberOfBytesRecvd and |pFlags are not updated. When the overlapped operation 
completes the amount of data transferred is indicated either through the cbTransferred 
parameter in the completion routine (if specified), or through the /ocbTransfer parameter 
in WSPGetOverlappedResult. Flag values are obtained either through the dwFlags 
parameter of the completion routine, or by examining the jodwFlags parameter of 
WSPGetOverlappedResult. 


Providers must allow this function to be called from within the completion routine of a 
previous WSPRecv, WSPRecvFrom, WSPSend or WSPSendTo function. However, for 
a given socket, I/O completion routines can not be nested. This permits time-sensitive 
data transmissions to occur entirely within a preemptive context. 


The /pOverlapped parameter must be valid for the duration of the overlapped operation. 
If multiple I/O operations are simultaneously outstanding, each must reference a 
separate overlapped structure. The oN etree structure has the 

following form: 


lf the |oCompletionRoutine parameter is NULL, the service provider signals the hEvent 
member of /oOverlapped when the overlapped operation completes if it contains a valid 
event object handle. The Windows Sockets SPI client can use 
WSPGetOverlappedResult to wait or poll on the event object. 


lf |poCompletionRoutine is not NULL, the hEvent member is ignored and can be used by 
the Windows Sockets SPI client to pass context information to the completion routine. A 
client that passes a non-NULL /oCompletionRoutine and later calls 


: WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait 


parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case the 


usage of the hEvent member is undefined, and attempting to wait on the hEvent member 


would produce unpredictable results. 


It is the service provider’s responsibility to arrange for invocation of the client specified— 
completion routine when the overlapped operation completes. Since the completion 
routine must be executed in the context of the same thread that initiated the overlapped 
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operation, it cannot be invoked directly from the service provider. The Ws2_32.dll offers 
an asynchronous procedure call (APC) mechanism to facilitate invocation of completion 
routines. 


A service provider arranges for a function to be executed in the proper thread and 
process context by calling WPUQueueApc, which was used to initiate the overlapped 
operation. This function can be called from any process and thread context, even a 

context different from the thread and process. that was used to initiate the overlapped 
operation. 


WPUQueueApc takes as input parameters a pointer to a WSATHREADID structure 
(supplied to the provider through the /oThreadid input parameter), a pointer to an APC 
function to be invoked, and a 32-bit context value that is subsequently passed to the 
APC function. Because only a single 32-bit context value is available, the APC function 
itself cannot be the client-specified completion routine. The service provider must instead 
supply a pointer to its own APC function that uses the supplied context value to access 
the needed result information for the overlapped operation, and then invokes the 
client-specified completion routine. 


The prototype for the client-supplied completion routine is as follows: 


CompletionRoutine is a placeholder for a client-supplied function name. dwError 
specifies the completion status for the overlapped operation as indicated by 
jpoOverlapped. cbTransferred specifies the number of bytes received. dwFlags contains 

~ information that would have appeared in /pFlags if the receive operation had completed 
immediately. This function does not return a value. 


The completion routines can be called in any order, but not necessarily the same order 
in which the overlapped operations are completed. However, the posted buffers are 
guaranteed to be filled in the same order in which they are supplied. 


Error Codes | 

Error code | Meaning | 

WSAENETDOWN Network subsystem has failed. 

WSAENOTCONN Socket is not connected. 

WSAEINTR | (Blocking) call was canceled through 

ol : WSPCancelBlockingCall. | 
WSAEINPROGRESS _ Blocking Windows Sockets call is in progress, or the: service 


provider is still processing acallbackfunction, = 
: (continued) 
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(continued) 


Error code 


WSAENETRESET 
WSAEFAULT 


WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


WSAEINVAL 


WSAECONNABORTED 
WSAECONNRESET 
WSAEDISCON 


WSA_IO_PENDING 


WSA_OPERATION_ABORTED 


Meaning 


Connection has been broken due to keep-alive activity 
detecting a failure while the operation was in progress. 


The /pBuffers argument is not totally contained in a valid part of | 
the user address space. 


Descriptor is not a socket. 


MSG_OOB was specified, but the socket is not stream-style 
such as type SOCK_STREAM, OOB data is not supported in 
the communication domain associated with this socket, or the 
socket is unidirectional and supports only send operations. 


Socket has been shut down; it is not possible to receive 
through WSPRecv on a socket after WSPShutdown has been 
invoked with how set to SD_RECEIVE or SD_BOTH. 


Overlapped sockets: there are too many outstanding 
overlapped I/O requests. Nonoverlapped sockets: The socket is 
marked as nonblocking and the receive operation cannot be 
completed immediately. 


Message was too large to fit into the specified buffer and (for 
unreliable protocols only) any trailing portion of the message 
that did not fit into the buffer has been discarded. 


Socket has not been bound (for example, with WSPBind) or 
the socket is not created with the overlapped flag. 


Virtual circuit was terminated due to a time-out or other failure. 
Virtual circuit was reset by the remote side. 

Socket s is message oriented and the virtual circuit was 
gracefully closed by the remote side. 

An overlapped operation was successfully initiated and 
completion will be indicated at a later time. 


Overlapped operation has been canceled due to the closure of 
the socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. — 


WPUCloseE vent, wPUCreateEvent, WSPGetOverlappedResult, WSPSocket, 


WPUQueueApc 
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WSPRecvDisconnect 


The WSPRecvDisconnect function terminates reception on a socket and retrieves the 
disconnect data, if the socket is connection oriented. 


Parameters 
S 


[in] Descriptor identifying a socket. 


IpinboundDisconnectData 
[out] Pointer to a buffer into which disconnect data is to be copied. 


loErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPRecvDisconnect returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /pErrno. 


Remarks 


WSPRecvDisconnect is used on connection-oriented sockets to disable reception, and 
retrieve any incoming disconnect data from the remote party. 


After this function has been successfully issued, subsequent receives on the socket will 
be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window 
is not changed and incoming data will be accepted (but not acknowledged) until the 
window is exhausted. For UDP, incoming datagrams are accepted and queued. In no 
case will an ICMP error packet be generated. 


To successfully receive incoming disconnect data, a Windows Sockets SPI client must 
use other mechanisms to determine that the circuit has been closed. For example, a 
client needs to receive an FD_CLOSE notification, or get a zero return value, ora 
WSAEDISCON error code from WSPRecv. 


Note that WSPRecvDisconnect does not close the socket, and resources attached to 
the socket will not be freed until WSPCloseSocket | is invoked. 
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Error Codes 
Error code 


Meaning 


Network subsystem has failed. 


WSAENETDOWN 
WSAEFAULT 


Buffer referenced by the parameter /p/nboundDisconnectData 


too small. 
WSAENOPROTOOPT _ Disconnect data is not supported by the indicated protocol 


IS 


ly 


fam 


ICe 


in progress, or the servi 


IS 


indows Sockets call 
provider is still processing a callback function. 


ing W 


Block 


WSAEINPROGRESS 


Socket is not connected (connection-oriented sockets only). 


WSAENOTCONN 
WSAENOTSOCK 


is not a socket 


tor 


Ip 


Descr 


Requires Windows Sockets 2.0. 


Header: Declared in Ws2spi.h. 


Version 


WSPConnect, WSPSocket 


WSPRecvFrom 


The WSPRecvFrom function receives a datagram and stores the source address. 
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Parameters 


Ss 
[in] Descriptor identifying a socket. 
loBuffers 
[in/out] Pointer to an array of WSABUF structures. Each MSABUr structure contains 
a pointer to a buffer and the length of the buffer. 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesRecvd 

[out] Pointer to the number of bytes received by this call. 

lpFlags 
[in/out] Pointer to flags. 

lpFrom 
[out] An optional pointer to a buffer that will hold the source address upon the 
completion of the overlapped operation. 


lpFromlen 
[in/out] Pointer to the size of the from butter, ence only if. PE LOM is ee peeed: 


IpOverlapped — 
[in] Pointer to a WSAOVERLAPPED structure tignored for nonoverlapped sockets). 


loCompletionRoutine 
[in] Pointer to the completion routine called when the receive operation has been 
completed (ignored for nonoverlapped sockets). 


lp Threadld 
[in] Pointer to a WSATHREADID structure to be used by the provider i in a subsequent 
call to WPUQueueApc. The provider should store the referenced WSATHREADID 
structure (not the pointer to same) until after the WPUQueueApc function returns. 


IpErmo 
[in/out] Pointer to the error code. 


: Return Values _ 


If no error occurs and the receive operation has completed immediately, WSPRecvFrom 

returns zero. Note that in this case the completion routine, if specified will have already 

been queued. Otherwise, a value of SOCKET_ERROR is returned, and a specific error 

_ code is available in /pErrno. The error code WSA_IO_PENDING indicates that the 

overlapped operation has been successfully initiated and that completion will be 

_ indicated at a later time. Any other error code indicates that no overlapped operations 
was initiated and no completion indication will occur. 
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Remarks 


WSPRecvFrom is used primarily on a connectionless socket specitied sii s. The socket 
must not be connected. The local address of the socket must be known. This may be 
done explicitly through WSPBind or implicitly through WSPSendTo or WSPJoinLeaf. 


For overlapped sockets, this function is used to post one or more buffers into which 
incoming data will be placed as it becomes available on a (possibly connected) socket, 
after which the client-specified completion indication (invocation of the completion 
routine or setting of an event object) occurs. If the operation does not complete 
immediately, the final completion status is retrieved through the completion routine or 
WSPGetOverlappedResult. Also note that the values pointed to by joFrom and 
lpFromlen are not updated until completion is indicated. Applications must not use or 
disturb these values until they have been updated, therefore the client must not use 
automatic (that is, stack-based) variables for these parameters. 


If both jpOverlapped and |pCompletionRoutine are NULL, the socket in this function will 
be treated as a nonoverlapped socket. 


For nonoverlapped sockets, the /oOverlapped, |poCompletionRoutine, and lpThreadld 
parameters are ignored. Any data that has already been received and buffered by the 
transport will be copied into the supplied user buffers. For the case of a blocking socket 
with no data currently having been received and buffered by the transport, the call will 
block until data is received according to the assigned blocking semantics for WSPRecv. 


The supplied buffers are filled in the order in which they appear in the array pointed to by 
loBuffers, and the buffers are packed so that no holes are created. 


The array of WSABUF structures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider's 
responsibility to capture this array of pointers to WSABUF structures before returning 
from this call. This enables Windows Sockets SPI clients to build stack-based WSABUF 
arrays. 


For connectionless socket types, the address from which the data originated is copied to 
the buffer pointed by /pFrom. On input, the value pointed to by /pFromlen is initialized to 
the size of this buffer, and is modified on completion to indicate the actual size of the 
address stored there. 


As noted previously for overlapped sockets, the /oFrom and |pFromlen parameters are 
not updated until after the overlapped I/O has completed. The memory pointed to by 
these parameters must, therefore, remain available to the service provider and cannot 
be allocated on the Windows Sockets SPI client's stack frame. The /oFrom and 
_IlpFromlen parameters are ignored for connection-oriented sockets. 


For byte stream style sockets (for example, type SOCK_STREAM), incoming data is 
placed into the buffers until the buffers are filled, the connection is closed, or internally 
buffered data is exhausted. Regardless of whether or not the incoming data fills all the 
buffers, the completion indication occurs for overlapped sockets. — 
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For message-oriented sockets, a single incoming message is placed into the supplied 
buffers, up to the total size of the buffers supplied, and the completion indication occurs 
for overlapped sockets. If the message is larger than the buffers supplied, the buffers are 
filled with the first part of the message. If the MSG_PARTIAL feature is supported by the 
service provider, the MSG_PARTIAL flag is set in /oflags for the socket and subsequent 
receive operation(s) will retrieve the rest of the message. If MSG_PARTIAL is not 
supported but the protocol is reliable, WSPRecvFrom generates the error 
WSAEMSGSIZE and a subsequent receive operation with a larger buffer can be used to 
retrieve the entire message. Otherwise, (that is, the protocol is unreliable and does not 
support MSG_PARTIAL), the excess data is lost, and WSPRecvFrom generates the 
error WSAEMSGSIZE. 


_lpFlags can be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is, the semantics of this function are 
determined by the socket options and the /pFlags parameter. The latter is constructed by 
using the bitwise OR operator with any of the following values. 


Value Meaning 
MSG_PEEK Peeks at the incoming data. The data is copied into the buffer but is 


not removed from the input queue. This flag is valid only for 
nonoverlapped sockets. 


MSG_OOB Processes OOB data (See DECnet Out-Of-band data for a discussion 
of this topic.) 


MSG_PARTIAL _ This flag is for message-oriented sockets only. On output, indicates 
_ that the data supplied is a portion of the message transmitted by the 
sender. Remaining portions of the message will be supplied in 
subsequent receive operations. A subsequent receive operation with 
MSG_PARTIAL flag cleared indicates end of sender’s message. 


As an input parameter, MSG_PARTIAL indicates that the receive 
operation should complete even if only part of a message has been 
received by the service provider. 


For message-oriented sockets, the MSG_PARTIAL bit is set in the /oFlags parameter if a 
partial message is received. If a complete message is received, MSG_PARTIAL is 
cleared in /pFilags. In the case of delayed completion, the value pointed to by /oFlags is 
not updated. When completion has been indicated the Windows Sockets SPI client 
should call rere) Oynappacresuit and examine the flags pointed to by the 
_lpdwFlags parameter. 


~ Overlapped Socket I/O 

If an overlapped operation completes immediately, WSPRecv returns a value of zero 
and the |oONumberOfBytesRecvd parameter is updated with the number of bytes received 
and the flag bits pointed by the /pFlags parameter are also updated. If the overlapped 
operation is successfully initiated and will complete later, WSPRecv returns 
SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
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loNumberOfBytesRecvd and /|pFlags is not updated. When the overlapped operation 
completes, the amount of data transferred is indicated either through the cbTransferred — 
parameter in the completion routine (if specified), or through the /ocbTransfer parameter 
in WSPGetOverlappedResult. Flag values are obtained by examining the lodwFlags 
parameter of WSPGetOverlappedResult. 


Providers must allow this function to be called from within the completion routine of a 
previous WSPRecv, WSPRecvFrom, WSPSend, or WSPSendTo function. However, 
for a given socket, I/O completion routines cannot be nested. This permits time-sensitive 
data transmissions to occur entirely within a preemptive context. 


The [pOverlapped parameter must be valid for the duration of the overlapped operation. 
If multiple I/O operations are simultaneously outstanding, each must reference a 
separate overlapped structure. The WSAOVERLAPPED structure has the following 
form: 


If the IoCompletionRoutine parameter is null, the service provider signals the hEvent 
member of /oOverlapped when the overlapped operation completes if it contains a valid 
event object handle. A Windows Sockets SPI client can use WSPGetOverlappedResult 
to wait or poll on the event object. | 


If JoOCompletionRoutine is not null, the hEvent member is ignored and can be used by the 
Windows Sockets SPI client to pass context information to the completion routine. It is 


_the service provider’s responsibility to arrange for invocation of the client-specified 


completion routine when the overlapped operation completes. Since the completion 
routine must be executed in the context of the same thread that initiated the overlapped 
operation, it cannot be invoked directly from the service provider. The Ws2_32.dll offers 
an asynchronous procedure call (APC) mechanism to facilitate invocation of completion 
routines. a 


_A service provider arranges for a function to be executed in the proper thread and 


process context by calling WPUQueueApc. This function can be called from any 
process and thread context, even a context different from the thread and process that 
was used to initiate the overlapped operation. 


WPUQueueApce takes as input parameters a pointer to a WSATHREADID structure 
(supplied to the provider through the /oThreaadld input parameter), a pointer to an APC 
function to be invoked, and a 32-bit context value that is subsequently passed to the 
APC function. Because only a single 32-bit context value is available, the APC function 
itself cannot be the client specified—completion routine. The service provider must 
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instead supply a pointer to its own APC function that uses the supplied context value to 
access the needed result information for the overlapped operation, and then invokes the 
client specified—completion routine. 


The prototype for the client-supplied completion routine is as follows: 


CompletionRoutine is a placeholder for a client-supplied function name. dwError 
specifies the completion status for the overlapped operation as indicated by 
IpOverlapped. cbTransferred specifies the number of bytes received. dwFlags contains 
information that would have appeared in /pFlags if the receive operation had completed 
immediately. This function does not return a value. 


The completion routines can be called in any order, though not necessarily in the same 
order that the overlapped operations are completed. However, the posted buffers are 
guaranteed to be filled in the same order they are supplied. 


Error Codes | | 
Error code | | _ Meaning ~~ 
WSAENETDOWN Network subsystem has failed. 
WSAEFAULT The /pFromlen argument was invalid: the /pFrom buffer was too 
| eae small to accommodate the peer address or /pbuffers is not 
totally contained within a valid part of the user address space. 
WSAEINTR (Blocking) call was canceled through 
, | . WSPCancelBlockingCall. : | 
WSAEINPROGRESS Blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. — | 
WSAEINVAL — Socket has not been bound (for example, with WSPBind) or 
? | the socket is not created with the overlapped flag. 
WSAEISCONN Socket is connected. This function is not permitted witha _ 
| connected socket, whether the socket is connection-oriented or 
| ~ connectionless. 
WSAENETRESET Connection has been broken due to keep-alive activity 
oe | ie detecting a failure while the operation was in progress. 
WSAENOTSOCK Descriptor is not a socket. 


| (continued) 
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(continued) 
Error code Meaning 
WSAEOPNOTSUPP MSG_OOB was specified, but the socket is not stream-style 


such as type SOCK_STREAM, OOB data is not supported in 
the communication domain associated with this socket, or the 
socket is unidirectional and supports only send operations. 


WSAESHUTDOWN Socket has been shut down; it is not possible to run 
WSPRecvFrom on a socket after WSPShutdown has been 
invoked with how set to SD__ RECEIVE or SD_BOTH. 


WSAEWOULDBLOCK Overlapped sockets: There are too many putstanaing 
overlapped I/O requests. 
Nonoverlapped sockets: The socket is marked as nonblocking 
and the receive operation cannot be completed immediately. 


WSAEMSGSIZE Message was too large to fit into the specified buffer and (for 
unreliable protocols only) any trailing portion of the message 
that did not fit into the buffer has been discarded. 


WSAECONNRESET The virtual circuit was reset by the remote side executing a 
hard or abortive close. The application should close the socket 
as it is no longer useable. On a UDP datagram socket this error 
would indicate that a previous send operation resulted in an 
ICMP “Port Unreachable” message. 


WSAEDISCON Socket s is message oriented and the virtual circuit was 
gracefully closed by the remote side. 
WSA_IO_PENDING An overlapped operation was successfully initiated and 


completion will be indicated at a later time. 


WSA_OPERATION_ABORTED Overlapped operation has been canceled due to the closure of 
the socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSocket, WSPGetOverlappedResult, WPUQueueApc 


wsPSelect 


The wsPSelect function determines the status of one or more sockets. 
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Parameters 


nfds 
[in] Ignored and included vay for the sake of sonpaliblity: 


readfds 
[in/out] An optional pointer to a set of sockets to be checked for readability. 


writeftds 
[in/out] An optional pointer to a set of sockets to be checked for ey 


excepttds 
[in/out] An optional pointer to a set of sockets to be checked for errors. 


__ timeout 
[in] Maximum time for wsPSelect to wait, or NULL for a blocking operation. 


~ IpErrno 
[out] Pointer to the error code. 


Return Values 


WSPSelect returns the total number of descriptors that are ready and contained in the 
FD_SET structures, or SOCKET_ERROR if an error occurred. If the return value is — 
SOCKET_ERROR, a specific error code is available in /pErrno. 


Remarks 


This function is used to determine the status of one or more sockets. For each socket, 
the caller can request information on read, write, or error status. The set of sockets for 
which a given status is requested is indicated by an FD_SET structure. All entries in an 
FD_SET correspond to sockets created by the service provider (that is, the 
WSAPROTOCOL_INFOW structures describing their protocols have the same 
providerld value). Upon return, the structures are updated to reflect the subset of these 
sockets that meet the specified condition, and WSPSelect returns the total number of 
sockets meeting the conditions. A set of macros is provided for manipulating an 
FD_SET. These macros are compatible with those used in the Berkeley software, but 
the underlying representation is completely different. 


The parameter readfds identifies those sockets that are to be checked for readability. If 
the socket is currently listening through WSPListen, it will be marked as readable if an 
incoming connection request has been received, so that a WSPAccept is guaranteed to 
complete without blocking. For other sockets, readability means that queued data is 
available for reading so that a WSPRecv or WSPRecvfrom is guaranteed not to block. 


626 


Volume 1 Winsock and QOS 


For connection-oriented sockets, readability can also indicate that a close request has 


_ been received from the peer. If the virtual circuit was closed gracefully, then a WSPRecv 


will return immediately with zero bytes read. If the virtual circuit was reset, then a 
WSPRecv will complete immediately with an error code, such as WSAECONNRESET. 
The presence of OOB data will be checked if the socket orn SO_OOBINLINE has 
been enabled (see WSPSetSockOpt). 


The parameter writefds identifies those sockets that are to be checked for writability: 


e lf asocket is connecting through WSPConnect, writability means that the connection 
establishment successfully completed. 


e |f the socket is not in the process of listening through WSPConnect, writability means 
that a WSPSend or WSPSendTo are guaranteed to succeed. 


However, they can block on a blocking socket if the /en exceeds the amount of outgoing 
system buffer space available. It is not specified how long these guarantees can be 
assumed to be valid, particularly in a multithreaded environment. 


The parameter excepifds identifies those sockets that are to be checked for the 
presence of OOB data or any exceptional error conditions. Note that OOB data will only 
be reported in this way if the option SO_OOBINLINE is FALSE. If a socket is making a 
WSPConnect (nonblocking) connection, failure of the connect attempt is indicated in 
excepttds. This specification does not define which other errors will be included. 


Any two of readfds, writefds, or exceptfds can be given as NULL if no descriptors are to 
be checked for the condition of interest. At least one must be non-NULL, and any non- 
NULL descriptor set must contain at least one socket descriptor. 


Summary: A socket will be identified in a particular set when WSPSelect returns 
according to the following: 


readfds: lf WSPListen is called, a connection is pending, WSPAccept will succeed. 
Data is available for reading (includes OOB data if SO_OOBINLINE 
_ is enabled). Connection has been closed/reset/terminated. 


writefds: lf WSPConnect (nonblocking), connection has succeeded. Data can 
be sent. 


Excepttds: lf WSPConnect (nonblocking), connection attempt failed. OOB data 
| is available for reading (only if SO_OOBINLINE is disabled). 


Three macros and one upcall function are defined in the header file Ws2spi.h for 
manipulating and checking the descriptor sets. The variable FD_SETSIZE determines 
the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, 
which can be modified by #defining FD_SETSIZE to another value before #including 
Ws2spi.h.) Internally, socket handles in a FD_SET are not represented as bit flags as in 
Berkeley Unix. Their data representation is opaque. Use of these macros will maintain 
software portability between different socket environments. 


- The macros to manipulate and check FD_SET contents are. 


Chapter 11 Winsock 2 SPI Reference 627 


FD_CLR(s, *sef) 

Removes the descriptor s from set. 
FD_SET(s, *se?) 

Adds descriptor s to set. 
FD_ZERO(*se?) 

Initializes the set to the NULL set. 


The upcall function used to check the membership is: 


int WPUFDIsSet (SOCKET s, FD_SET FAR * set); 
which will return nonzero if s is a member of the set or otherwise zero. 


The parameter timeout controls how long the WSPSelect can take to complete. If 
timeout is a NULL pointer, WSPSelect will block indefinitely until at least one descriptor 
meets the specified criteria. Otherwise, timeout points to a TIMEVAL structure that 
specifies the maximum time that WSPSelect should wait before returning. When 
WSPSelect returns, the contents of the TIMEVAL structure are not altered. If TIMEVAL 
is initialized to {0, 0}, WSPSelect will return immediately; this is used to poll the state of 
the selected sockets. If this is the case, then the WSPSelect call is considered 
nonblocking and the standard assumptions for nonblocking calls apply. For example, the 
blocking hook will not be called, and the Windows Sockets provider will not yield. 


Note WSPSelect has no effect on the persistence of socket events registered with 
WSPAsyncSelect or WSPEventSelect. 


Error Codes 


Error code Meaning 

WSAEFAULT Windows Sockets service provider was unable to allocated needed 
resources for its internal operations, or the readfds, writefds, exceptfds or 
timeval parameters are not part of the user address space. , 

WSAENETDOWN __ Network subsystem has failed. | 

WSAEINVAL The timeout value is not valid, or all three descriptor bid otal were 
NULL. 

WSAEINTR | (Blocking) call was canceled through WSPCancelBlockingCall 


WSAEINPROGRESS _ Blocking Windows Sockets call is in progress, or the service ne is 


still processing a callback function. 


~WSAENOTSOCK —_s One of the eee Pier sets contains an aay that is nota socket 


_ Version: Requires Windows Sockets 2.0. 
| Header: Declared in Ws2spi.h. 
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WSPAccept, WSPConnect, WSPRecv, WSPRecvFrom, WSPSend, WSPSendTo, 
WSPEventSelect 


WSPSend 


The WSPSend function sends data on a connected socket. 


a 
pea 


se 


es 


eee 


Parameters 


S 
in] Descriptor identifying a connected socket. 


uffers 

in] Pointer to an array of WSABUF structures. Each WSABUF structure contains a_ 
pointer to a buffer and the length of the buffer. This array must remain valid for the 
duration of the send operation. 


dwBufferCount 
[in] Number of WSABUF structures in the /oBuffers array. 


loNumberOfBytesSent 
[out] Pointer to the number of bytes sent by this call. 


dwFlags 
[in] Specifies the way in which the call is made. 


IpOverlapped — | 
[in] Pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets.) 


lp>CompletionRoutine | | 
[in] Pointer to the completion routine called when the send operation has been 
completed (ignored for nonoverlapped sockets.) 


lp Threadld | 7 | | 
[in] Pointer to a WSATHREADID structure to be used by the provider in a subsequen 
call to WPUQueueApce. The provider should store the referenced WSATHREADID 
structure (not the pointer to same) until after the WPUQueueApc function returns. 
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loErrno 
[out] Pointer to the error code. 


Return Values 

If no error occurs and the send operation has completed immediately, WSPSend returns 
zero. Note that in this case the completion routine, if specified, will have already been 
queued. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code 
is available in /oErrno. The error code WSA_IO_PENDING indicates that the overlapped 
operation has been successfully initiated and that completion will be indicated at a later 
time. Any other error code indicates that no overlapped operation was initiated and no 
completion indication will occur. 


Remarks | 

WSPSend is used to write outgoing data from one or more buffers on a connection- 
oriented socket specified by s. It can also be used, however, on connectionless sockets 
that have a stipulated default peer address established through the WSPConnect 
function. 


For overlapped sockets (created using WSPSocket with flag 
WSA_FLAG_OVERLAPPED) this will occur using overlapped I/O, unless both 
lpOverlapped and |oCompletionRoutine are NULL in which case the socket is treated as 
a nonoverlapped socket. A completion indication will occur (invocation of the completion 
routine or setting of an event object) when the supplied buffer(s) have been consumed 
by the transport. If the operation does not complete immediately, the final completion 
status is retrieved through the completion routine or WSPGetOverlappedResult. 


For nonoverlapped sockets, the parameters /pOverlapped, |pCompletionRoutine, and 

lo Threadlid are ignored and WSPSend adopts the regular synchronous semantics. Data 
is copied from the supplied buffer(s) into the transport’s buffer. If the socket is | 
nonblocking and stream oriented, and there is not sufficient space in the transport’s 
buffer, WSPSend will return with only part of the supplied buffers having been 
consumed. Given the same buffer situation and a blocking socket, WSPSend will block 
until all of the supplied buffer contents have been consumed. 


The array of WSABUF structures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider’s 
responsibility to capture these WSABUF structures before returning from this call. This 
enables applications to build stack-based WSABUF arrays. 


For message-oriented sockets, care must be taken not to exceed the maximum 
message size of the underlying provider, which can be obtained by getting the value of 
socket option SOQ_MAX_MSG_SIZE. If the data is too long to pass atomically through 
the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. 


_ Note that the successful completion of a WSPSend does not indicate that the data was - 
successfully delivered. 
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dwFlags can be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is, the semantics of this function are 
determined by the socket options and the dwFlags parameter. The latter is constructed 
by using the bitwise OR operator with any of the following values. 


Value Meaning 


MSG_DONTROUTE Specifies that the data should not be subject to routing. A 
Windows Sockets service provider can choose to ignore 


| this flag;. 
MSG_OOB Sends OOB data (stream-style socket such as 
SOCK_STREAM only). 
MSG_PARTIAL Specifies that /oBuffers only contains a partial message. Note 


that the error code WSAEOPNOTSUPP will be returned for 
messages that do not support partial message transmissions. 


Overlapped Socket I/O 


lf an overlapped operation completes immediately, WSPSend returns a value of zero 
and the joNumberOfBytesSent parameter is updated with the number of bytes sent. If 
the overlapped operation is successfully initiated and will complete later, WSPSend 
returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
loNumberOfBytesSent is not updated. When the overlapped operation completes the 
amount of data transferred is indicated either through the cbTransferred parameter in the 
completion routine (if specified), or through the locbTransfer parameter in 
WSPGetOverlappedResult. 


Providers must allow this function to be called from within the completion routine of a 
previous WSPRecv, WSPRecvFrom, WSPSend or WSPSendTo function. However, for 
a given socket, I/O completion routines cannot be nested. This permits time-sensitive 


- data transmissions to occur entirely within a preemptive context. 


The ijpOverlapped parameter must be valid for the duration of the overlapped operation. 


_ If multiple I/O operations are simultaneously outstanding, each must reference a 


separate overlapped structure. The WSAOVERLAPPED structure has the 
following form: 
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If the joCompletionRoutine parameter is NULL, the service provider signals the hEvent 
member of JoOverlapped when the overlapped operation completes if it contains a valid 
event object handle. The Windows Sockets SPI client can use 
WSPGetOverlappedResult to wait or poll on the event object. 


lf j|oCompletionRoutine is not NULL, the hEvent member is ignored and can be used by 
the Windows Sockets SPI client to pass context information to the completion routine. A 
client that passes a non-NULL /pCompletionRoutine and later calls 
WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait 
parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case the 
usage of the hEvent member is undefined, and atempnng to wait on the hEvent member 
would produce unpredictable results. 


A service provider arranges for a function to be executed in the proper thread and 
process context by calling WPUQueueApc. This function can be called from any 
process and thread context, even a context different from the thread and process that 
was used to initiate the overlapped operation. 


A service provider arranges for a function to be executed in the proper thread by calling 
WPUQueueApc. Note that this function must be invoked while in the context of the 
same process (but not necessarily the same thread) that was used to initiate the 
overlapped operation. It is the service provider’s responsibility to arrange for this process 
context to be active prior to calling WPUQueueApc. © 


WPUQueueApc takes as input parameters a pointer to a WSATHREADID structure 
(supplied to the provider through the /oThreadid input parameter), a pointer to an APC 
function to be invoked, and a 32-bit context value that is subsequently passed to the 
APC function. Because only a single 32-bit context value is available, the APC function 

_ itself cannot be the client specified—completion routine. The service provider must 
instead supply a pointer to its own APC function that uses the supplied context value to 
access the needed result information for the overlapped operation, and then invokes the 
client specified—completion routine. 


The prototype for the client-supplied completion routine is as follows: 


CompletionRoutine isa placeholder for a client supplied function name. dwError 
specifies the completion status for the overlapped operation as indicated by | 
|pDOverlapped. cbTransferred specifies the number of bytes sent. No flag values are. 
currently defined and the dwFlags value will be zero. This function does not 

return a value. 
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The completion routines can be called in any order, though not necessarily in the same 
order that the overlapped operations are completed. However, the service provider 
guarantees to the client that posted buffers are sent in the same order they are supplied. 


Error Codes 
Error code 


WSAENETDOWN 
WSAEACCES 


WSAEINPROGRESS 
WSAEFAULT 


WSAENETRESET 
WSAENOBUFS 


WSAENOTCONN 
WSAENOTSOCK 
WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 
WSAEINVAL 


WSAECONNABORTED 
WSAECONNRESET 


WSA_OPERATION_ 
ABORTED 


Meaning 


Network subsystem has failed. 

Requested address is a broadcast address, but the appropriate flag 
was not set. 

Blocking Windows Sockets call is in progress, or the service provider is 
still processing a callback function. 

The /pBuffers argument is not totally contained in a valid part of the 
user address space. 

Connection has been broken due to the remote host resetting. 
Connection has been broken due to keep-alive activity ee a 
failure while the operation was in progress. 

Socket is not connected. 

Descriptor is not a socket. 

MSG_OOB was specified, but the socket is not stream-style such as 
type SOCK_STREAM, OOB data is not supported in the 
communication domain associated with this socket, MSG_PARTIAL is 


not supported, or the socket is unidirectional and supports only receive 
Operations. _ 

Socket has been shut down; it is not possible to WSPSend on a socket 
after WSPShutdown has been invoked with how set to SD_SEND or 
SD_BOTH. 

Overlapped sockets: There are too many outstanding overlapped |/O 
requests. 

Nonoverlapped sockets: The socket is marked as nonblocking and the 
send operation cannot be completed immediately. 

Socket is message oriented, and the message is larger than the 
maximum supported by the underlying transport. 

Socket has not been bound with WSPBind, or the socket is not created 
with the overlapped flag. 

Virtual circuit was terminated due to a time-out or other failure. 

Virtual circuit was reset by the remote side. 


Overlapped operation has been canceled due to the sigsure of the 
socket, or the execution of the SIO. FLUSH command in WSPloctil. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSocket, WSPGetOverlappedResult, WPUQueueApc 


WSPSendDisconnect 


The WSPSendDisconnect function initiates termination of the connection for the socket 
and sends disconnect data. 


Parameters 
S 


[in] A descriptor identifying a socket. 


|pOutbounadDisconnectData | 
[in] A pointer to the outgoing disconnect data. 


lpErrno | 
[out] A pointer to the error code. 


Return Values 


If no error occurs, WSPSendDisconnect returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /pErrno. 


Remarks 


-WSPSendDisconnect is used on connection-oriented sockets to disable transmission, 
and to initiate termination of the connection along with the transmission of disconnect 
data, if any. | 


Aiter this function has been successfully issued, subsequent sends are disallowed. 


|p OutboundDisconnectData, if not NULL, points to a buffer containing the outgoing 
disconnect data to be sent to the remote party. 


Note that WSPSendDisconnect does not close the socket, and that resources attached 
to the socket will not be freed until WSPCloseSocket is invoked. — 
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Note WSPSendDisconnect does not block regardless of the SO_LINGER setting on 
the socket. 


A Windows Sockets SPI client should not rely on being able to reuse a socket after it has 
been disconnected. In particular, a Windows Sockets provider is not required to support 
the use of WSPConnect on such a socket. 


Error Codes 
Error code Meaning 
WSAENETDOWN Network subsystem has failed. 


WSAENOPROTOOPT Parameter /oOutboundDisconnectData is not NULL, and the 
disconnect data is not supported by the service provider. 


WSAEINPROGRESS Blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. 


WSAENOTCONN Socket is not connected (connection-oriented sockets only). 
WSAENOTSOCK Descriptor is not a socket. 
WSAEFAULT The /pOutboundDisconnectData argument is not totally 


contained in a valid part of the user address space. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSocket 


WSPSendTo 


The WSPSendTo function sends data to a specific destination using overlapped I/O. 
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Parameters 
S 


[in] A descriptor identifying a socket. 


lpBuffers 
[in] A pointer to an array of WSABUF structures. Each WSABUF structure contains a 
pointer to a buffer and the length of the buffer. This array must remain valid for the 
duration of the send operation. 


dwBufferCount 
[in] The number of WSABUF structures in the /pBuffers array. 


loNumberOfBytesSent 
[out] A pointer to the number of bytes sent by this call. 


dwFlags | 
{in] Specifies the way in which the call is made. 
loTo 
[in] An optional gues to the address of the target socket. 


iTolen 
[in] The size of the address in /pTo. 


IpOverlapped 
[in] A pointer to a WSAOVERLAPPED structure (ignored for nonpwenlapped sockets). 


lpCompletionRoutine 
[in] A pointer to the pena routine called when the send operation has been 
completed (ignored for nonoverlapped sockets). 


lp Threadld 
[in] A pointer to a WSATHREADDID structure to be used by the provider ina 
subsequent call to WPUQueueApc. The provider should store the referenced 
WSATHREADID structure (not the pointer to same) until after the WPUQueueApc 
function returns. 

IpErrno | 
lout] A pointer to the error code. 


Return Values 


If no error occurs and the receive operation has completed immediately, WSPSendTo 
returns zero. Note that in this case the completion routine, if specified, will have already 
been queued. Otherwise, a value of SOCKET_ERROR is returned, and a specific error 
code is available in /pErrno. The error code WSA_IO_PENDING indicates that the 
overlapped operation has been successfully initiated and that completion will be 
indicated at a later time. Any other error code indicates that no overlapped operation 
was initiated and no completion indication will occur. | 
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Remarks 


WSPSendTo is normally used on a connectionless socket specified by s to send a 
datagram contained in one or more buffers to a specific peer socket identified by the 
lo To parameter. Even if the connectionless socket has been previously connected to a 
specific address with the connect function, /oTo overrides the destination address for 
that particular datagram only. On a connection-oriented socket, the JoTo and iToLen 
parameters are ignored; in this case the WSPSendTo function is equivalent to 
WSPSend. 7 


For overlapped sockets (created using WSPSocket with flag 
WSA_FLAG_OVERLAPPED) this will occur using overlapped I/O, unless both 
lpOverlapped and lpCompletionRoutine are NULL in which case the socket is treated as 
a nonoverlapped socket. A completion indication will occur (invocation of the completion 
routine or setting of an event object) when the supplied buffer(s) have been consumed 
by the transport. If the operation does not complete immediately, the final completion 
status is retrieved through the completion routine or WSPGetOverlappedResult. 


For nonoverlapped sockets, the parameters /pOverlapped, |pCompletionRoutine, and 

lp Threadid are ignored and WSPSendTo adopts the regular synchronous semantics. 
Data is copied from the supplied buffer(s) into the transport’s buffer. If the socket is 
nonblocking and stream oriented, and there is not sufficient space in the transport’s 
buffer, WSPSendTo will return with only part of the Windows Sockets SPI client’s buffers 
having been consumed. Given the same buffer situation and a blocking socket, 
WSPSendTo will block until all of the Windows Sockets SPI client’s buffer contents have 
been consumed. 


The array of WSABUF structures pointed to by the /oBuffers parameter is transient. If 
this operation completes in an overlapped manner, it is the service provider’s 
responsibility to capture these WSABUF structures before returning from this call. This 
enables applications to build stack-based WSABUF arrays. 


For message-oriented sockets, care must be taken not to exceed the maximum 
message size of the underlying transport, which can be obtained by getting the value of 
socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through 
the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted. 


Note that the successful completion of a WSPSendTo does not indicate that the data 
was successfully delivered. 


iFlags can be used to influence the behavior of the function invocation beyond the 
options specified for the associated socket. That is, the semantics of this function are 
determined by the socket options and the dwFlags parameter. The latter is constructed 
by using the bitwise OR operator with any of the values on the following page. 


Chapter 11 Winsock 2 SPI Reference 637 


Value Meaning 


MSG_DONTROUTE _ Specifies that the data should not be subject to routing. A 
Windows Sockets service provider can choose to ignore 


this flag. 

MSG_OOB Sends OOB data (stream-style socket such as 
SOCK_STREAM only). 

MSG_PARTIAL Specifies that /oBuffers only contains a partial message. Note 


that the error code WSAEOPNOTSUPP will be returned by 
transports that do not support partial message transmissions. 


Overlapped Socket I/O 

lf an overlapped operation completes immediately, WSPSendTo returns a value of zero 
and the JoNumberOfBytesSent parameter is updated with the number of bytes sent. If 
the overlapped operation is successfully initiated and will complete later, WSPSendTo 
returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, 
lpNumberOfBytesSent is not updated. When the overlapped operation completes the 
amount of data transferred is indicated either through the cbTransferred parameter in the 
~ completion routine (if specified), or through the /jocbTransfer parameter in 
WSPGetOverlappedResult. 


Providers must allow this function to be called from within the completion routine of a 
previous WSPRecv, WSPRecvFrom, WSPSend or WSPSen¢dTo function. However, for 
a given socket, I/O completion routines cannot be nested. This permits time-sensitive 
data transmissions to occur entirely within a preemptive context. 


The IpOverlapped parameter must be valid for the duration of the overlapped operation. 
lf multiple I/O operations are simultaneously outstanding, each must reference a 
separate overlapped structure. The WSAOVERLAPPED structure has the 

following form: 


If the IpCompletionRoutine parameter is NULL, the service provider signals the hEvent 

member of /pOverlapped when the overlapped operation completes if it contains a valid 
~ event object handle. Windows Sockets SPI clients can use WSPGetOverlappedResult 
to wait or poll on the event object. 


lf IpCompletionRoutine i is not NULL, the hEvent member is ignored and can be used by 
the Windows Sockets SPI client to pass context information to the completion routine. A 
client that passes a non-NULL lpCompletionRoutine and later calls 
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WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait 
parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case the 
usage of the hEvent member is undefined, and attempting to wait on the hEvent member 
would produce unpredictable results. | 


It is the service provider’s responsibility to arrange for invocation of the client specified— 
completion routine when the overlapped operation completes. Since the completion 
routine must be executed in the context of the same thread that initiated the overlapped 
operation, it cannot be invoked directly from the service provider. The Ws2_32.dll offers 
an asynchronous procedure call (APC) mechanism to facilitate invocation of completion 
routines. 


A service provider arranges for a function to be executed in the proper thread by calling 
WPUQueueApc. This function can be called from any process and thread context, even 
a context different from the thread and process that was used to initiate the overlapped 
operation. 


WPUQueueApc takes as input parameters a pointer to a WSATHREADID structure 
(supplied to the provider through the /oThreadid input parameter), a pointer to an APC 
function to be invoked, and a 32-bit context value that is subsequently passed to the 
APC function. Because only a single 32-bit context value is available, the APC function 
itself cannot be the client specified—completion routine. The service provider must 
instead supply a pointer to its own APC function, which uses the supplied context value 
to access the needed result information for the overlapped operation, and then invokes 
the client specified—completion routine. 


The prototype for the client-supplied completion routine is as follows: 


CompletionRoutine is a placeholder for a client-supplied function name. dwError 
specifies the completion status for the overlapped operation as indicated by 
IpOverlapped. cbTransferred specifies the number of bytes sent. No flag values are 
currently defined and the dwFlags value will be zero. This function does not return a 
value. | ~ 


The completion routines can be called in any order, though not necessarily in the same 
order that the overlapped operations are completed. However, the service provider 


guarantees to the client that posted buffers are sent in the same order they are supplied. 


Error Codes 
Error code 


WSAENETDOWN 
WSAEACCES 


WSAEINTR 
WSAEINPROGRESS 


WSAEFAULT 
WSAENETRESET 


-WSAENOBUFS 
WSAENOTCONN 
WSAENOTSOCK 

~ WSAEOPNOTSUPP 


WSAESHUTDOWN 


WSAEWOULDBLOCK 


WSAEMSGSIZE 


~WSAEINVAL, 


WSAECONNABORTED 


WSAECONNRESET 


WSAEADDRNOTAVAIL 
WSAEAFNOSUPPORT 
WSAEDESTADDRREQ > 


WSAENETUNREACH 


WSA_OPERATION_ 
ABORTED 
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Meaning 
Network subsystem has failed. 


Requested address is a broadcast address, but the appropriate flag 
was not set. 


(Blocking) call was canceled through WSPCancelBlockingCall. 
Blocking Windows Sockets call is in progress, or the service provider is 
still processing a callback function. 

The /pBuffers or loTo parameters are not part of the user address 
space, or the /oTo argument is too small. 

Connection has been broken due to keep-alive activity detecting a 
failure while the operation was in progress. 

Windows Sockets provider reports a buffer deadlock. 

Socket is not connected (connection-oriented sockets only.) 
Descriptor is not a socket. 

MSG_OOB was specified, but the socket is not stream-style such as 
tyoe SOCK_STREAM, OOB data is not supported in the | 
communication domain associated with this socket, MSG_PARTIAL is 
not supported, or the socket is unidirectional and supports only receive 
operations. 


Socket has been shut down; it is not possible to use WSPSendTo ona 
socket after WSPShutdown has been invoked with how set to 
SD_SEND or SD_BOTH. 


Overlapped sockets: there are too many outstanding overlapped I/O 


~ requests. Nonoverlapped sockets: The socket is marked as 


nonblocking and the send operation cannot be completed immediately. 


Socket is message oriented, and the message is larger than the 
maximum supported by the underlying transport. | 


Socket has not been bound with WSPBind, or the socket is not 


- created with the overlapped flag. 


Virtual circuit was terminated due to a time-out or other failure. 
Virtual circuit was reset by the remote side. | 
Remote address is not a valid address (for example, ADDR_ANY). 


_ Addresses in the specified family cannot be used with this socket. 


Destination address is required. 
Network cannot be reached from this host at this time. 
Overlapped operation has been canceled due to the closure of the 


_ socket, or the execution of the SIO_FLUSH command in WSPloctl. 
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Windows Sockets 2.0. 


ires 
Declared in Ws2spi.h. 


Requi 


Version 
Header 


WSPSocket, WSPGetOverlappedResult, WPUQueueApc 


WSPSetSockOpt 


The WSPSetSockOpt function sets a socket option. 


Parameters 
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WSPSetSockOpt sets the current value for a socket option associated with a socket of 
any type, in any state. Although options can exist at multiple protocol levels, they are 
always present at the uppermost socket’ level. Options affect socket operations, such as 
whether broadcast messages can be sent on the socket. 


There are two types of socket options: Boolean options that enable or disable a feature 
or behavior, and options that require an integer value or structure. To enable a Boolean 
option, optval points to a nonzero integer. To disable the option, optval points to an 
integer equal to zero. The optlen parameter should be equal to sizeof (int) for Boolean 
options. For other options, optval points to the an integer or structure that contains the 
desired value for the option, and optlen is the length of the integer or structure. 


level = SOL_SOCKET 


Value 
SO BROADCAST 
SO DEBUG 


SO_DONTLINGER 
SO_DONTROUTE 


SO GROUP PRIORITY 


SO_KEEPALIVE 


SO _LINGER 
SO OOBINLINE 
SO_RCVBUF 


- SO_REUSEADDR 


_ $0 _ SNDBUF 


PVD_CONFIG 


Type 
BOOL 


BOOL 
BOOL 
BOOL 


int 
BOOL 


struct linger 
BOOL 
int 


BOOL 
int 


Service 
Provider 


~ Dependent 


Meaning 

Allows transmission of broadcast messages on the 
socket. 

Records debugging information. 

Reserved. | 

Does not route: sends directly to interface. Not 


~ Supported on ATM sockets (results in an error). 


Reserved. 

Sends keep-alives. Not supported on ATM sockets 
(results in an error). | 

Lingers on close if unsent data is present. 

Receives OOB data in the normal data stream. 
Specifies the total per-socket buffer space reserved for 


receives. This is unrelated to SO_MAX_MSG_SIZE or 
the size of a TCP window. | 


Allows the socket to be bound to an address that is 
already in use. (See bind.) Not applicable on ATM 
sockets. 

Specifies the total per-socket buffer space reserved for 
sends. This is unrelated to SO_ MAX_MSG_SIZE or the 
size of a TCP window. 

This object stores the configuration information for the 
service provider associated with socket s. The exact 
format of this data structure is service provider specific. 


Calling WSPGetSockOpt with an unsupported option will result in an error ce of 
Se RENOPROTOOET being returned in IpErgno. 
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SO_DEBUG | 
Windows Sockets service providers are encouraged (but not required) to supply 
output debug information if the SO_DEBUG option is set by a Windows Sockets SPI 
client. The mechanism for generating the debug information and the form it takes are 
beyond the scope of this specification. 


SO GROUP _ PRIORITY 
Reserved. 


SO_KEEPALIVE 
A Windows Sockets SPI client can request that a TCP/IP provider enable the use of 
keep-alive packets on TCP-connections by turning on the SO_KEEPALIVE socket 
option. A Windows Sockets provider need not support the use of keep-alives: if it 
does, the precise semantics are implementation specific but should conform to 
section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts—Communication 
Layers. If a connection is dropped as the result of keep-alive the error code 
WSAENETRESET is returned to any calls in progress on the socket, and any 
subsequent calls will fail with WSAENOTCONN. 


SO_LINGER 
SO_LINGER controls the action taken when unsent data is queued on a socket and a 
WSPCloseSocket is performed. See WSPCloseSocket for a description of the way ~ 
in which the SO_LINGER settings affect the semantics of WSPCloseSocket. The 
Windows Sockets SPI client sets the desired behavior by creating a struct linger 
(pointed to by the optval argument) with the following elements: 


To enable SO_LINGER, a Windows Sockets SPI client should set /_onoffto a 
nonzero value, set /_linger to zero or the desired time-out (in seconds), and call 
WSPSetSockOpt. To enable SO_DONTLINGER (that is, disable SO_LINGER) 
| onoff should be set to zero and WSPSetSockOpt should be called. Note that 
enabling SO_LINGER with a nonzero time-out on a nonblocking socket is not 
recommended (see section 4.7.7. WSPCloseSocket for details.) — 


Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if 
SO_DONTLINGER is disabled (that is, SO_LINGER is enabled) then no time-out 
value is specified. In this case, the time-out used is implementation dependent. If a 
previous time-out has been established for a socket (by enabling SO_LINGER), then 
this time-out value should be reinstated by the service provider. 


SO_REUSEADDR se 
By default, a socket cannot be bound (see WSPBind) to a local address that is 
already in use. On occasion, however, it may be desirable to reuse an address in this 
way. Since every connection is uniquely identified by the combination of local and 
remote addresses, there is no problem with having two sockets bound to the same 
local address as long as the remote addresses are different. To inform the Windows 
sockets provider that a WSPBind on a socket should be allowed to bind to a local 
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address that is already in use by another socket, the Windows Sockets SPI client 
should set the SOQ_REUSEADDR socket option for the socket before issuing the 
WSPBind. Note that the option is interpreted only at the time of the WSPBind: it is 
therefore unnecessary (but harmless) to set the option on a socket that is not to be 

_ bound to an existing address, and setting or resetting the option after the WSPBind 
has no effect on this or any other socket. 


SO_SNDBUF 
When a Windows Sockets implementation supports the SO_RCVBUF and 
SO_SNDBUF options, a Windows Sockets SPI client can request different buffer 
sizes (larger or smaller). The call can succeed even though the service provider did 
not make available the entire amount requested. A Windows Sockets SPI client must 
call WSPGetSockOpt with the same option to check the buffer size actually provided. 


PVD_CONFIG 
This object stores the configuration information for the service provider associated 
with socket s. The exact format of this data structure is service provider specific. 


Error Codes 

Error code Meaning 

WSAENETDOWN Network subsystem has failed. © 

WSAEFAULT The optval is not in a valid part of the process address space 


or optien argument is too small. 
WSAEINPROGRESS _ Function is invoked when a callback is in progress. 


WSAEINPROGRESS Blocking Windows Sockets call is in progress, or the service 
provider is still processing a callback function. 


WSAEINVAL The /evel/ is not valid, or the information in optval is not valid. 


WSAENETRESET Connection has been broken due to keep-alive activity 
| detecting a failure while the operation was in progress. 


WSAENOPROTOOPT Option is unknown or unsupported for the specified provider. 
WSAENOTCONN Connection has been reset when SO_KEEPALIVE is set. 


WSAENOTSOCK Descriptor is not a socket. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPBind, WSPGetSockOpt, WSPloctl, WSPSocket, WSPEventSelect_ 
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WSPShutdown 


The WSPShutdown function disables sends and/or receives on a socket. 


Parameters 


Ss 
[in] Descriptor identifying a socket. 


how 
[in] Flag that describes what types of operation will no longer be allowed. 


lpErrno 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPShutdown returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /oErrno. 


Remarks 


WSPShutdown is used on all types of sockets to disable reception, 
transmission, or both. 


If how is SD_RECEIVE, subsequent receives on the socket will be disallowed. This has 
no effect on the lower protocol layers. For TCP sockets, if there is still data queued on 
the socket waiting to be received, or data arrives subsequently, the connection is reset, 
since the data cannot be delivered to the user. For UDP sockets, incoming datagrams 
are accepted and queued. In no case will an ICMP error packet be generated. 


If how is SD_SEND, subsequent sends on the socket are disallowed. For TCP sockets, 
a FIN will be sent. Setting how to SD_BOTH disables both sends and receives as 
described above. 


Note that WSPShutdown does not close the socket, and resources attached to the 
socket will not be freed until WSPCloseSocket is invoked. 


Note WSPShutdown does not block regardless of the SO_LINGER setting on the 
socket. A Windows Sockets SPI client should not rely on being able to reuse a socket 
after it has been shut down. In particular, a Windows Sockets service provider i is not 
required to support the use of WSPConnect on such a socket. 
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Error Codes 


Meaning 


Error code 
WSAENETDOWN 


WSAEINVAL 


Network subsystem has failed. 


t consistent with the socket type. 
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The WSPSocket function creates a socket. 


Parameters 


af 


[in] Address family specification. 


type 


in] Type specification for the new socket. 


protocol 


[in] Protocol to be used with the socket that is specific to the indicated address family. 
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loProtocolinfo 
[in] Pointer to a WSAPROTOCOL_INFOW structure that defines the characteristics of 
the socket to be created. 


[in] Reserved. 


dwFlags 
Socket attribute specification. 


loErrno 
[out] Pointer to the error code. 


Return Values 

If no error occurs, WSPSocket returns a desennie: referencing the new socket. 
Otherwise, a value of INVALID_SOCKET is returned, and a specific error code is 
available in /oErrno. 


Remarks 

WSPSocket causes a socket descriptor and any related resources to be allocated. By 
default, the created socket will not have the overlapped attribute. Windows Sockets 
providers are encouraged to be realized as Windows installable file systems, and supply 
system file handles as socket descriptors. These providers must call 
WPUModifylFSHandle prior to returning from this function. For nonfile-system Windows 
Sockets providers, WPUCreateSocketHandle must be used to acquire a unique socket 
descriptor from the Ws2_32.dll prior to returning from this function. See section 
Descriptor Allocation for more information. 


The values for af, type, and protoco/ are those supplied by the application in the 
corresponding API functions socket or WSASocket. A service provider is free to ignore 
or pay attention to any or all of these values as is appropriate for the particular protocol. 
However, the provider must be willing to accept the value of zero for af and type, since 
the Ws2_32.dll considers these to be wildcard values. Also the value of manifest 


~ constant FROM_PROTOCOL_INFO must be accepted for any of af, type and protocol. 


This value indicates that the Windows Sockets 2 application needs to use the 
corresponding values from the indicated WSAPROTOCOL_INFOW structure: 
(iAddressFamily, isocketType, iProtocol). 


The dwFlags parameter can be used to specify the attributes of the socket by using the 
bitwise OR operator with any of the flags on the following page. 
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Flag | | Meaning 
WSA_FLAG_ This flag causes an overlapped socket to be created. Overlapped 
OVERLAPPED sockets can utilize WSPSend, WSPSendTo, WSPRecv, 


WSPRecvFrom and WSPloctl for overlapped I/O operations, which 
allow multiple operations to be initiated and in process simultaneously. 
All functions that allow overlapped operations also support 
nonoverlapped usage on an overlapped socket if the values for 
parameters related to overlapped operation are NULL. 


WSA_FLAG_ Indicates that the socket created will be a c_root in a multipoint 
MULTIPOINT_C_ROOT _ session. Only allowed if a rooted control plane is indicated in the 
protocol’s WSAPROTOCOL_INFOW structure. 


WSA._FLAG__ Indicates that the socket created will be a c_leaf in a multicast session. 
MULTIPOINT_C_LEAF Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the 
protocols WSAPROTOCOL_INFOW structure. 


WSA_FLAG_ | Indicates that the socket created will be a d_root in a multipoint 
MULTIPOINT_D_ROOT _ session. Only allowed if a rooted data plane is indicated in the 
| ~-- protocol’s WSAPROTOCOL_INFOW structure. 


WSA_FLAG_ Indicates that the socket created will be a d_leaf in a multipoint 
MULTIPOINT_D_LEAF _ session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in 
the protocols WSAPROTOCOL_INFOW structure. 


Important For multipoint sockets, exactly one of WSA_FLAG_MULTIPOINT_C_ROOT 
or WSA_FLAG_MULTIPOINT_C_LEAF must be specified, and exactly one of © 
WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF must be 
specified. Refer to Protocol-Independent Multicast and Multipoint in the SPI for additional 
information. © 7 


Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, 
and must be in a connected state before any data can be sent or received on them. A 
connection to another socket is created with a WSPConnect call. Once connected, data 
can be transferred using WSPSend and WSPRecv calls. When a session has been 
completed, a WSPCloseSocket must be performed. 


The communications protocols used to implement a reliable, connection-oriented socket 
ensure that data is not lost or duplicated. If data for which the peer protocol has buffer 
space cannot be successfully transmitted within a reasonable length of time, the 
connection is considered broken and subsequent calls will fail with the error code setto 
WSAETIMEDOUT. | 


Connectionless, message-oriented sockets allow sending and receiving of datagrams to 
and from arbitrary peers using WSPSendTo and WSPRecvFrom. If such a socket is 
connected by using WSPConnect to a specific peer, datagrams can be sent to that peer 
using WSPSend and can be received from (only) this peer using WSPRecv. 
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Support for sockets with type SOCK RAW is not required but service providers are 
encouraged to support raw sockets whenever it makes sense to do so. 


Shared Sockets 


When a special WSAPROTOCOL_INFOW structure (obtained through the 
WSPDuplicateSocket function and used to create additional descriptors for a shared 
socket) is passed as an input parameter to WSPSocket, the g and dwFlags 


parameters are ignored. 


Layered Service Provider Considerations 


A layered service provider supplies an implementation of this function, but it is also a 
Client of this function if and when it calls WSPSocket of the next layer in the protocol 
chain. Some special considerations apply to this function’s /pProtocolinfo parameter as it 
is propagated down through the layers of the protocol chain. 


If the next layer in the protocol chain is another layer then when the next layer’s 
WSPSocket is called, this layer must pass to the next layer a /oProtocollnfo that 
references the same unmodified WSGAPROTOCOL_INFOW structure with the same 
unmodified chain information. However, if the next layer is the base protocol (that is, the 
last element in the chain), this layer performs a substitution when calling the base 
providers WSPSocket. In this case, the base providers WSAPROTOCOL_INFOW 
structure should be referenced by the /pProtocollnfo parameter. 


One vital benefit of this policy is that base service providers do not have to be aware of 


protocol chains. 


This same propagation policy applies when propagating a WSAPROTOCOL_INFOW 
structure through a layered sequence of other functions such as WSPAddressToString, 
WSPDuplicateSocket, WSPStartup, or WSPStringToAddress. 


Error Codes 
Error code 


WSAENETDOWN 


WSAEAFNOSUPPORT 
WSAEINPROGRESS 


WSAEMFILE 
WSAENOBUFS 


WSAEPROTONOSUPPORT 
WSAEPROTOTYPE 
WSAESOCKTNOSUPPORT 


WSAEINVAL 


Meaning 
Network subsystem has failed. 


Specified address family is not supported. 


Blocking Windows Sockets call is in progress, or the 
service provider is still processing a callback function. 


No more socket descriptors are available. 


No buffer space is available. The socket cannot be 


created. 

Specified protocol is not supported. 

Specified protocol is the wrong type for this socket. 
Specified socket type is not supported in this address 
family. : 

Parameter g specified is not valid. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPAccept, WSPBind, WSPConnect, WSPGetSockName, WSPGetSockOpt, 
WSPSetSockOpt, WSPListen, WSPRecv, WSPRecvFrom, WSPSend, WSPSendTo, 
WSPShutdown, WSPloctl, WPUCreateSocketHandle 


WSPStartup 


The WSPStartup function initiates use of a Windows Sockets service provider by a 
client. — 


Parameters 


wVersionRequested | | 

[in] Highest version of Windows Sockets SPI support that the caller can use. The 
high-order byte specifies the minor version (revision) number; the low-order byte 
specifies the major version number. 


IpWSPData 
[out] Pointer to the WSPDATA data structure that is to receive details of the Windows 
Sockets service provider. 


lpoProtocollnfo 
[in] Pointer to a WSAPROTOCOL_INFOW structure that defines the characteristics of 
the desired protocol. This is especially useful when a single provider DLL is capable 
of instantiating multiple different service providers. 


UpcallTable 
[in] Ws2_32.dll’s upcall dispatch table. 


lpProcTable 
_ fout] Pointer to the table of SPI function pointers. 


Return Values 


WsPStartup returns zero if successful. Otherwise, it returns one of the error codes listed 
below: 
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Remarks 


This function must be the first Windows Sockets SPI function called by a Windows 
Sockets SPI client on a per-process basis. It allows the client to specify the version of 
Windows Sockets SPI required and to provide its upcall dispatch table. All upcalls (that 
is, functions prefixed with WPU) made by the Windows Sockets service provider are 
invoked through the client’s upcall dispatch table. This function also allows the client to 
retrieve details of the specific Windows Sockets service provider implementation. The 
Windows Sockets SPI client can only issue further Windows Sockets SPI functions after 
a successful WSPStartup invocation. A table of pointers to the rest of the SPI functions 
is retrieved through the /pProcTable parameter. 


In order to support future versions of the Windows Sockets SPI and the Ws2_32.dll, 
which may have functionality differences from the current Windows Sockets SPI, a 
negotiation takes place in WSPStartup. The caller of WSPStartup (either the 
Ws2_32.dll or a layered protocol) and the Windows Sockets service provider indicate to 
each other the highest version that they can support, and each confirms that the other’s 
highest version is acceptable. Upon entry to WSPStartup, the Windows Sockets service 
provider examines the version requested by the client. If this version is equal to or higher 
than the lowest version supported by the service provider, the call succeeds and the 
service provider returns in wHighVersion the highest version it Supports and in wVersion 
the minimum of its high version and wVersionRequested. The Windows Sockets service 
provider then assumes that the Windows Sockets SPI client will use wVersion. If the 
wVersion member of the WSPDATA structure is unacceptable to the caller, it should call 
WSPCleanup and either search for another Windows Sockets service provider or fail to 
initialize. 

This negotiation allows both a Windows Sockets service provider and a Windows 
Sockets SPI client to support a range of Windows Sockets versions. A client can 
successfully utilize a Windows Sockets service provider if there is any overlap in the 
version ranges. | 


The following chart gives examples of how WSPStartup works in conjunction with 


different Ws2_32.dll and Windows Sockets service provider (SP) versions. 


DLL 
versions 


1.1 
1.01.1 
1.0 
1.1 
1.1 
1.0 
1.01.1 
1.12.0 
2.0 


SP wVersion wHigh 

versions requested wVersion’§ version’ End result 

1.1 1.1 1.1 1.1 use 1.1 

1.0 1.1 1.0 1.0 use 1.0 

1.0 1.1 1.0 1.0 1.1 use 1.0 

1.0 1.1 1.1 1.1 1.1 use 1.1 

1.0 1.1 1.0 1.0 DLL fails 

1.1 1.0 “<= --- WSAVERNOTSUPPORTED 
1.0 1.1 1.1 1.1 1.1 use 1.1 | 

1.1 2.0 1.1 1.1 use 1.1 


2.0 2.0 —— 2.0 2.0 use 2.0 
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The following code fragment demonstrates how a Windows Sockets SPI client, which 
supports only version 2 of Windows Sockets SPI, makes a WSPStartup call: 


So 


And this code fragment demonstrates how a Windows Sockets service provider that 
supports only version 2 performs the WSPStartup negotiation. 
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A Windows Sockets SPI client can call WSPStartup more than once if it needs to obtain 
the WSPData structure information more than once. On each such call the client can 
specify any version number supported by the provider. 


There must be one WSPCleanup call corresponding to every successful WSPStartup 
call to allow third-party DLLs to make use of a Windows Sockets provider. This means, 
for example, that if WSPStartup is called three times, the corresponding call to 
WSPCleanup must occur three times. The first two calls to WSPCleanup do nothing 
except decrement an internal counter; the final WSPCleanup call does all necessary 
resource deallocation. 


This function (and most other service provider functions) can be invoked in a thread that 
started out as a 16-bit process if the client is a 16-bit Windows Sockets 1.1 client. One 
important limitation of 16-bit processes is that a 16-bit process cannot create threads. 
This is significant to service provider implementers that plan to use an internal service 
thread as part of the implementation. 


Fortunately, there are usually only two areas where the conditions for a service thread 
are strong: 


e In the implementation of overlapped I/O completion. 
e In the implementation of WSPEventSelect. 


Both of these areas are only accessible through new Windows Sockets 2 functions, 
which can only be invoked by 32-bit processes. 


A service thread can be safely used if these two design rules are carefully followed: 


e Use a service thread only for functionality that is unavailable to 16-bit Windows 
Sockets 1.1 clients. | 


e Create the service thread only on demand. 


Several other cautions apply to the use of internal service threads. First, threads 
generally carry some performance penalty. Use as few as possible, and avoid thread 
transitions wherever possible. Second, your code should always check for errors in 
creating threads and fail gracefully and informatively (for example, with 
WSAEOPNOTSUPP) in case some execution event you did not expect results in a 16- 
bit process executing a code path that needs threads. | 


Layered Service Provider Considerations 


A layered service provider supplies an implementation of this function, but itis also a 
Client of this function when it calls WSPStartup to initialize the next layer in the protocol 
chain. The call to the next layers WSPStartup may happen during the execution of this 
layers WSPStartup or it may be delayed and called on demand, such as when 
WSPSocket is called. In any case, some special considerations apply to this function’s 
IpProtocolinfo parameter as it is propagated down ard the layers of the oie 
chain. : 
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The layered provider searches the Protoco/Chain of the structure referenced by 
loProtocolinfo to determine its own location in the chain (by searching for the layer’s own 
catalog entry /d) and the identity of the next element in the chain. If the next element is 
another layer, then, when the next layers WSPStartup is called, this layer must pass to 
the next layer a /oProtocolinfo that references the same unmodified 
WSAPROTOCOL_INFOW structure with the same unmodified chain information. 
However, if the next layer is the base protocol (that is, the last element in the chain), this 
layer performs a substitution when calling the base provider's WSPStartup. In this case, 
the base providers WSAPROTOCOL_INFOW structure should be referenced by the 
lpProtocolinfo parameter. | 


One vital benefit of this policy is that base service providers do not have to be aware of 
protocol chains. 


This same propagation policy applies when propagating a WSAPROTOCOL_INFOW 
structure through a layered sequence of other functions such as WSPAddressToString, 
WSPDuplicateSocket, WSPSocket, or WSPStringToAddress. 


Error Codes 


Error code Meaning 
WSASYSNOTREADY Indicates that the underlying network subsystem is not 


ready for network communication. 


WSAVERNOTSUPPORTED Version of Windows Sockets SPI support requested is 
not provided by this particular Windows Sockets service 


provider. 
WSAEINPROGRESS Blocking Windows Sockets operation is in progress. 
WSAEPROCLIM Limit on the number of clients supported by the Windows 
| | sockets implementation has been reached. 
WSAEFAULT The joWSPData or IpProcTable parameter is invalid. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 


WSPSend, WSPSendTo, WSPCleanup 


WSPStringToAddress 


The WSPStringToAddress function converts a human-readable numeric string to a 
socket address structure (SOCKADDR) suitable to passing to Windows Sockets routines 
that take such a structure. 
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Any missing components of the address will be defaulted to a reasonable value if 
possible. For example, a missing port number will default to zero. 


Parameters 


AddressString 
— [in] Points to the zero-terminated human-readable string to convert. 


AddressFamily ; 
[in] Address family to which the string belongs, or AF_UNSPEC if it is unknown. 


lpProtocolinfo 7 
[in] (required) Providers WSAPROTOCOL_INFOW structure. | | 


lpAddress | . i oe ? | 
[out] Buffer that is filled with a single SOCKADDR structure. 

IpAddressLength _ | | oe 
[in/out] Length of the Address buffer. Returns the size of the resultant SOCKADDR 


structure. If the supplied buffer is not large enough, the function fails with a specific 
error of WSAEFAULT and this parameter is updated with the required size in bytes. 


lpErrno | 
[out] Pointer to the error code. 


Return Values 


If no error occurs, WSPStringToAddress returns zero. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /oErrno. 


Layered Service Provider Considerations 


_ A layered service provider supplies an implementation of this function, but it is also a 
client of this function if and when it calls WSPStringToAddress of the next layer in the 
‘protocol chain. Some special considerations apply to this function’s /oProtocolinfo 
parameter as it is propagated down through the layers of the protocol chain. 
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If the next layer in the protocol chain is another layer then when the next layer’s 
WSPStringToAddress is called, this layer must pass to the next layer a /oProtocollnfo 
that references the same unmodified WSAPROTOCOL_INFOW structure with the same 
unmodified chain information. However, if the next layer is the base protocol (that is, the 
last element in the chain), this layer performs a substitution when calling the base 
provider's WSPStringToAddress. In this case, the base provider’s 
WSAPROTOCOL_INFOW structure should be referenced by the /pProtocolinfo 
parameter. 


One vital benefit of this policy is that base service providers do not have to be aware of 
protocol chains. 


This same propagation policy applies when propagating a WSAPROTOCOL_INFOW 
structure through a layered sequence of other functions such as WSPAddressToString, 
WSPDuplicateSocket, WSPStartup, or WSPSocket. 


Error Codes 
Errorcode Meaning 


WSAEFAULT Specified address buffer is too small. Pass in a larger buffer. 


WSAEINVAL Unable to translate the string into a SOCKADDR, or the provider was 
unable to support the indicated address family, or the specified 
IpProtocolinfo did not refer to a WSAPROTOCOL_INFOW structure 
supported by the provider. 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Ws2spi.h. 
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CHAPTER 12 


Winsock 2 Protocol-Specific Annex 


This chapter describes the Microsoft® Windows® Sockets 2 Protocol-Specific Annex. It 
presents information drawn from the Windows Sockets 2 Protocol-Specific Annex 
specification. 


Using the Annex 


This chapter and its sections provide the information needed to create a Windows 
Sockets (Winsock) application for Microsoft® Windows NT®/Windows® 2000, 

Windows 98®, and Windows 95® operating systems, using the Microsoft implementation 
of Windows Sockets 2. It is intended as a reference tool and outlines the functions in the 
Windows Sockets Protocol-Specific Annex. 


To make the best use of this chapter, you should have a working knowledge of Microsoft 
Win32® programming concepts. The Win32® Developer’s Reference Library, another 
library in the Windows Programming Reference Series (WPRS) is available from 
Microsoft Press. If you do not have a working knowledge of Win32®, you may want to 
refer to the Win32 Developer's Reference Library or, other references that provide a 
more systematic guide to writing Winsock applications. | 


Note This documentation is intended for application developers. If you are developing a 
transport or service provider, see the Service Provider documentation installed with the 
Platform SDK. | 


Overview of Windows Sockets 2 


Windows Sockets 2 is a superset of the widely deployed Windows Sockets 1.1. Windows 
Sockets 2 extends the 1.1 interface in a number of areas while maintaining full backward 
compatibility. Among other enhancements, it provides access to protocols other than 
TCP/IP. Winsock enables an application to use the familiar socket interface to achieve 
simultaneous access to any number of installed transport protocols. 


While most of these protocols may be used with standard Windows Sockets 2—interface | 
mechanisms, each supported protocol contains conventions and behaviors that | 
developers need to be aware of. Some individual protocols support special features that 
do not lend themselves to being treated generically. This document provides the details 
that developers need to effectively use all of the supported protocols. 
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Microsoft Extensions and Windows Sockets 2 


The Windows Sockets 2 specification defines an extension mechanism that exposes 
advanced transport functionality to application programs. For more information, see 
Function Extension Mechanism. 


The following Microsoft-specific extensions were added to Windows Sockets 1.1. They 
are also available in Windows Sockets 2: 

e AcceptEx 

e GetAcceptExSockaddrs 

e TransmitFile 

e WSARecvEx 


These functions are not exported from the Ws2_32.dll; they are exported from 
Mswsock.dll. 


An application written to use the Microsoft-specific extensions to Winsock will not run 
correctly over a Windows Sockets service provider that does not support those 
extensions. 


socket Handles for Windows Sockets 2 

A socket handle can optionally be a file handle in Windows Sockets 2. It is possible to 
use socket handles with ReadFile, WriteFile, ReadFileEx, WriteFileEx, | 
DuplicateHandle, and other Win32 functions. Not all transport service providers will 
support this option. However, for an application to run over the widest possible number 
of service providers, it should not assume that socket handles are file handles. 


Windows Sockets 2 has expanded certain functions that transfer data between sockets 
using handles. The functions offer advantages specific to sockets for transferring data 
and include WSARecv, WSASend, and WSADuplicateSocket. 


TCP/IP 


This section describes TCP/IP functions, data structures, and TCP/IP controls. 


TCP/IP Introduction 


This section covers extensions to Windows Sockets 2 that are specific to TCP/IP 
protocols. It also describes aspects of base Windows Sockets 2 functions that require 
special consideration or that may exhibit unique behavior when using TCP/IP. 
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Fast Facts 

Protocol name(s) TCP, UDP 

Description Provides two transport services over the IP networking layer: 
UDP for unreliable datagrams, TCP for reliable, connection- 
oriented byte streams. 

Address family AF_INET 

Header file Ws2tcpip.h 


TCP/IP Overview 


The TCP/IP protocol suite forms the backbone of the global Internet. The original 
Windows Sockets specification (version 1.1) addressed only TCP/IP protocols, and still 


contains a few |IP-specific attributes. | 


Two basic types of transport services are offered: unreliable datagrams (UDP), and 
reliable connection-oriented byte streams (TCP). In addition, a raw socket is optionally 
supported. Raw sockets allow an application to communicate through protocols other 
than TCP and UDP such as ICMP. 


TCP/IP Data Structures 


The INTERFACE_INFO structure is used in conjunction with the 
SIO_GET_INTERFACE_LIST ioctl command. It is defined in Ws2tcpip.h file and is 


reproduced here. 


Members 

liFlags , 
A bitmask describing the status of the interface. The following flags are possible. 
Flag Meaning 
IFF_UP | The interface is running. 
IFF_BROADCAST | The broadcast feature is supported. 
IFF_LOOPBACK The loopback interface is running. 
IFF_POINTTOPOINT The interface is using point-to-point link. 


IFF MULTICAST = ~—~—__:s The multicast feature is supported. 
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iiAddress 
The address of the interface. 


liBroadcastAddress 
The broadcast address of the interface or the address of the other side for point-to- 
point links. 


liNetmask 
The netmask used by the interface. 


TCP/IP Controls 


The following controls are available in all TCP/IP implementations: 


e UNIX loctls 
e TCP/IP Socket Options 


UNIX loctis 


The SIOGIFCONF command provided by most UNIX implementations is supported in 
the form of WSAloctl and WSPloctl functions with the command 
SIO_GET_INTERFACE_LIST. This command returns the list of configured interfaces 
and their parameters. Support of this command is mandatory for Windows Sockets 2 
compliant-TCP/IP service providers. 


The parameter /ovOutBuffer points to the buffer in which WSAloctl and WSPloctl store 
the information about interfaces. The number of interfaces (number of structures 
returned in /ovOutBuffer) can be determined based on the actual length of the output 
buffer returned in jocbBytesReturned. 


TCP/IP Socket Options 


The following TCP/IP-specific options are defined. 


Value | Meaning 

SIO_GET_INTERFACE_LIST Returns a list of all IP interfaces on the system. 

level=IPPROTO_IP 

Value Type Meaning 

IP_OPTIONS char FAR * Lists IP options to be inserted into 
the outgoing packets. 

IP_TOS int Specifies the type of service to be 


used. See following for more 
information about setting TOS. 


IP_TTL | int Specifies the TTL to be used. 


Value 


IP_HDRINCL 


IP_MULTICAST_IF 


IP_MULTICAST_TTL 
IP_MULTICAST_LOOP 


IP_ADD_MEMBERSHIP 


IP_DROP_MEMBERSHIP 


level= IPPROTO_UDP 


Value 


UDP_NOCHECKSUM 


level= IPPROTO._ TCP 
Value 


TCP EXPEDITED 1122 


Chapter 12 Winsock 2 Protocol-Specific Annex 661 


Type 
BOOL 


IN_ADDR FAR 
*structure 


int 
BOOL 


IP_MREQ FAR * 
structure 


IP_MREQ FAR * 
structure 


Type 
‘BOOL 


Type 
BOOL 


Meaning 


If TRUE, the application provides the 
IP header in the packets sent over 
SOCK_RAW interface. Otherwise, 
the header is provided by the service 
provider. 


Selects the interface for the outgoing 
multicast packets. The optval/ should 
point to the address of the interface 
to be used. If NULL, the default 
interface is used. 


TTL used for the multicast packets. 


lf TRUE, multicast loopback is 
enabled. Otherwise, it is disabled. 


Specifies the multicast group to join. 


Specifies the multicast group to 
leave. 


Meaning 


If this option is set, UDP datagrams are 
sent with the checksum of zero. This | 
option is required. If a service provider 
does not have a mechanism to disable 
UDP checksum calculation, it may 
simply store this option without taking 
any action. : 


Meaning 


lf set, the SP implements the expedited 
data as specified in RFC-1222. 
Otherwise, the BSD style (default) is 
used. This option can be set on the 
connection only once, that is, once on, 
this option can not be turned off. This 
option is not required. 
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IP_OPTIONS 
Specifies IP options to be inserted into outgoing datagrams. Setting the new options 
overwrites all the previously specified options. Setting optva/ to zero means removing 
all previously specified options. The support of IP_OPTIONS is not required. In order 
to check whether IP_OPTIONS is supported, an application should use getsockopt 
to attempt to get the current options. If getsockopt fails, the IP_OPTIONS is not 
supported. | 


IP_TOS 
Changes the default value set by the TCP/IP service provider in the TOS field of the 
IP header in outgoing datagrams. The support of IP_TOS is not required. To check 
whether IP_TOS is supported, an application should use getsockopt to attempt to get 
the current options. If getsockopt fails, the IP_TOS is not supported. 


There are two important points to keep in mind regarding TOS: 


e TOS and IP precedence bits have been deprecated, and the corresponding TOS 
RFC obviated, by Diffserv code point (DSCP). Many DSCP values have been 
recommended for standardization by the IETF. For more information about these 

standardization recommendations, consult the IETF Web site at www./etf.org and 
look into the Diffserv working group. 


e Programmers should never directly set TOS bits. Use the QOS API to set the bits. 
Diffserv code point is explained in the Quality of Service SDK reference section. 


It is important to note that when QOS is enabled on a Windows 2000 computer, all 
TOS settings are overridden by settings implemented or set using the traffic control 
API (TC API) or the QOS API. 


IP_TTL 
Changes the default value set by the TCP/IP service provider in the TTL field of the IP 
header in outgoing datagrams. The support of IP_TTL is not required. In order to 

— check if IP_TTL is supported, an application should use getsockopt to attempt to get 
the current options. If getsockopt fails, the IP_TTL is not supported. 


IP_HDRINCL : | 
By default TCP/IP service provider forms the IP header for the outgoing datagrams. 
Some applications, however, may wish to provide their own IP header. Such 
applications should set IP_HDRINCL option to TRUE and then supply a completed IP 
header at the front of each outgoing datagram. The only modification TCP/IP service 
provider may make to the supplied IP header is setting the ID field, if the value 
supplied by the application is 0. The IP_HDRINCL option is applied only to the 
SOCK_RAW type of protocol. If a TCP/IP service provider supports SOCK_RAW | 
protocol, it should also support IP_HDRINCL option. 


IP_MULTICAST_IF 

Information supplied at a later release. 
IP_MULTICAST_TTL 

Information supplied at a later release. 


IP_MULTICAST_LOOP 
Information supplied at a later release. 
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IP_ADD_MEMBERSHIP 
Information supplied at a later release. 


IP_DROP_MEMBERSHIP 
Support of these options is required if a protocol supports multicast. This will be 
indicated in the WSAPROTOCOL_INFO structure returned by WSAEnumProtocols 
as follows: 
XPI_SUPPORTS_MULTIPOINT = 1 
XP1_MULTIPOINT_CONTROL_PLANE = 0 


XP1_MULTIPOINT_DATA_PLANE = 0 


TCP/IP Function Details 


This section presents general information about TCP/IP function details for multicast, 
raw sockets, and Ipv6 support. : 


Multicast 


Generic Winsock multipoint functions support IP multicast. However, the TCP/IP 
transport providers who support multicast must also provide BSD style—multicast support 
by supporting the corresponding multicast options. This will simplify the porting of 
existing multicast applications to Windows Sockets 2. 


TCP/IP Raw Sockets 


The TCP/IP service providers may Support the SOCK_ RAW sockel nye. There are two 
types of such sockets: 


e The first type assumes a known protocol type as written in the IP header. An example 
of the first type of socket is ICMP. 


e The second type allows any protocol number. An example of the second type would 
be an experimental protocol that is not supported by the service provider. 


Ifa TCP/IP service provider supports SOCK_RAW sockets for the AF_ INET family, the 
corresponding protocol(s) should be included in the list returned by 
WSAEnumProtocols. The jpProtoco! field of the WSAPROTOCOL_INFO structure may 
be set to zero if the service provider allows an application to specify any value for the 
protocol parameter for the Socket, WSASocket, and WSPSocket functions. — 


Note An application may not specify zero (0) as the protocol parameter for the Socket, | 
| WSASocket, and WSPSocket functions if SOCK_RAW sockets are used. 


The following rules are applied to the operations. over SOCK. RAW eceketa:. 


e When an application sends a datagram it may or may not include the IP header at the 
front of the oo datagrams depending on the IP_ HDRINCL option set for the 
socket. : 
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e An application always gets the IP header at the front of each received datagram 
regardless of the IP_HDRINCL option. | 


e Received datagrams are copied into all SOCK_RAW sockets that satisfy the following 
_ conditions: 


e The protocol number specified for the socket should match the protocol number in 
the IP header of the received datagram. 


e lf alocal IP address is defined for the socket, it should correspond to the 
destination address as specified in the IP header of the received datagram. An 
application may specify the local IP address by calling bind functions. If no local IP 
address is specified for the socket, the datagrams are copied into the socket 
regardless of the destination IP address in the IP header of the received datagram. 


e lf aforeign address is defined for the socket, it should correspond to the source 
address as specified in the IP header of the received datagram. An application may 
specify the foreign IP address by calling connect functions. If no foreign IP 
address is specified for the socket, the datagrams are copied into the socket 
regardless of the source IP address in the IP header of the received datagram. 


It is important to understand that SOCK_RAW sockets may get many unexpected 
datagrams. For example, a PING program may use SOCK_RAW sockets to send ICMP 
echo requests. While the application is expecting ICMP echo responses, all other ICMP 
messages (such as ICMP HOST_UNREACHABLE) may be delivered to this application 
also. Moreover, if several SOCK_RAW sockets are open on a machine at the same 
time, the same datagrams may be delivered to all the open sockets. An application must 
have a mechanism to recognize its datagram and to ignore all others. Such mechanism 
may include inspecting the received IP header—using unique identifiers in the ICMP 
header (ProcessID, for example), and so forth. 


Note On Windows NT/Windows 2000, raw socket support requires administrative 
privileges. Users running Winsock applications that make use of raw sockets must have 
administrative privileges on the computer, otherwise raw socket calls fail with an error 

_ code of WSAEACCESS. 


IPv6 Support 

If TCP/IP service provider supports IPv6 addressing, it must install itself twice: 
e Once for IPv4. 

e Once for IPv6 address family. 


So, WSAEnumProtocols returns two WSAPROTOCOL_INFO structures for each of the 
supported socket types (SOCK_STREAM, SOCK_DGRAM, SOCK_RAW). The 
iAddressFamily must by set to AF_INET for IPv4 addressing, and to AF_INET6 for IPv6 
addressing. 


The IPv6 addresses are described in the following structures. 
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The IPv6 addresses are described in the following structures: 


If an application uses Windows Sockets 1.1 functions and wants to use IPv6 addresses, 
it may continue to use all the old functions that take the SOCKADDR structure as one of 
the parameters (bind, connect, sendto, and recvfrom, accept, and so forth). The only 
change that is required is to use SOCKADDR_ING6 instead of SOCKADDR. 


However, the name resolution functions (gethostbyname, gethostbyaddr, and so forth 
and address conversion functions (inet_addr, inet_ntoa) can not be reused because 
they assume an IP address 4 bytes in length. An application that wants to perform name 
resolution and address conversion for IPv6 addresses must use the Windows Sockets 2- 
specific functions (WSAStringToAddress, WSAAddressToString, and so forth). 


Text Representation of IPv6 Addresses 


This section is copied from the IP Version 6 Addressing Architecture by R.Hinden and S. 
Deering. There are three conventional forms for representing IPv6 addresses as text 


strings: 


e The preferred form is X:X:X:X:X:X:X:X, where the “x’s are the hexadecimal values of the 
eight 16-bit pieces of the address. | | 


Examples: 
FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 


1080:0:0:0:8:800:200C:417A 


Note It is not necessary to write the leading Zeros in an individual field, but there 
must be at least one numeral in every field (except for the case described in the 


second form). 


e Due to the method of allocating certain styles of IPv6 addresses, it is common for 
addresses to contain long strings of zero bits. In order to make writing addresses 
containing zero bits easier, a special syntax is available to compress the zeros. The 
use of double quotation marks (*::”) indicates multiple groups of 16-bits of zeros. 


For example, the multicast address | 
FFO1:0:0:0:0:0:0:43 _ 

may be represented as: 
FFO1::43 
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The double quotation marks (“::”) can only appear once in an address. They can be 
used to compress leading or trailing zeros in an address. 


An alternative form that may be more convenient when dealing with a mixed 
environment of IPv4 and IPv6 nodes is x:x:x:x:x:x:d.d.d.d, where the “x’s are the 
hexadecimal values of the six high-order 16-bit pieces of the address, and the “d’s are 
the decimal values of the four low-order 8-bit pieces of the address (standard IPv4 
representation). 


Examples: 
0:0:0:0:0:0:13.1.68.3 
0:0:0:0:0:FFFF:129.144.52.38 
or in compressed form: 
:13.1.68.3 
FFFF:129.144.52.38 


TCP/IP Header File 


Use the Ws2tcpip.h header file for TCP/IP transactions. 


IPX/SPX 


This section introduces and provides important specifics for IPX/SPX: 


IPX/SPX Introduction 


This section covers extensions to Windows Sockets 2 that are specific to the IPX family 
of transport protocols. It also describes aspects of base Windows Sockets 2 functions 
that require special consideration or that may exhibit unique behavior. 


Fast Facts 
Protocol name(s) IPX, SPX 
Description Provides transport services over the IPX networking layer: IPX 
| for unreliable datagrams, SPX for reliable, connection-oriented 
message streams. | 
‘Address family AF_IPX 


Header file | Wsipx.h 


IPX/SPX Overview 


This section discusses how to use the Windows Sockets 2 API with the IPX family of 
protocols. Traditionally, the Windows Sockets 1.x specification has been used with the IP 
family of protocols such as TCP and UDP. With the advent of Windows Sockets 2, the 
API has been updated to access a wide range of transport and network types more 
easily. 
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The Windows Sockets 2 API is sufficiently generic. That is, programmers need to know 
very little about the specifics of the IPX/SPX implementation. However, if you are moving 
traditional IPX applications to Winsock or want more knowledge of the IPX/SPX 
implementation, this appendix is for you. Be aware that IPX networks operate differently 
than IP networks; consideration of this fact will most likely be manifest in your code. — 


IPX/SPX features are defined in the header file Wsipx.h. 


AF_IPX Address Family 


The IPX address family defines the addressing structure for protocols that use standard 
IPX socket addressing. For these transports, an endpoint address consists of a network 
number, node address, and socket number. 


The network number is an administrative domain and typically names a single Ethernet 
or token ring segment. The node number is a station’s physical address. The 
combination of net and node form a unique station address that is presumed to be 
unique in the world. Net and node numbers are represented in ASCII text in either block 
or dashed notation as: “0101a040,00001b498765” or “O01-01-a0-40,00-00-1b-49-87-65”. 
Leading zeros need not be present. 


The IPX socket number is a network/transport service number much like a TCP port 

number and is not to be confused with the Winsock socket descriptor. IPX socket 

numbers are global to the end station and cannot be bound to specific net/node 

addresses. For instance, if the end station has two network interface cards, a bound 

socket can send and receive on both cards. In particular, datagram sockets would 
receive broadcast datagrams on both cards. 


Caution SOCKADDF_IPX is 14 bytes long and is shorter than the 16-byte 
SOCKADDR reference structure. IPX/SPX implementations may accept the 16-byte 
length as well as the true length. If you use SOCKADDR_IPX and a hard-coded length 
of 16 bytes, the implementation may assume that it has access to the 2 bytes following 
your structure. 


Field ‘ Value 
sa_family Address family AF_IPX in host order. 

- Sa_netnum | IPX network identifier in network order. 
Sa_nodenum  — Station node address, flushed right. 


Sa_socket - IPX socket number in network order. 


IPX Family of Protocol Identifiers 


The protocol parameter in socket and WSASocket is an identifier that establishes a 
network type and a method for identifying the various transport protocols that run on the: 
network. Unlike IP, IPX does not use a single protocol value for selecting a transport 
stack. Since there is no network requirement to use a specific value for each transport 
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protocol, we are free to assign them in a manner convenient for Winsock applications. 
We avoid values 0-255 in order to avoid collisions with the corresponding PF_INET 
protocol values. 


Name Value Socket types Description 
Reserved 0-255 Reserved for PF_INET protocol 
| values. 
NSPROTO_IPX 1000-1255 SOCK_DGRAM ___ Datagram service for IPX. 
SOCK_RAW 
NSPROTO_SPX 1256 SOCK_STREAM Peliable packet exchange 


SOCK_SEQPKT _ using fixed-sized packets. 


Note When NSPROTO_SPxX is specified, the SPX II protocol is automatically utilized if 
both endpoints are capable of doing so. 


Broadcast to Local Network 


A broadcast can be made to the locally attached network by setting sa_netnum to binary 
zeros and sa_nodenum to binary ones. This broadcast may be sent to the primary © 
network for the device, or to all locally attached networks at the option of the service 
provider. Broadcasts to the local network are not propagated by routers. 


All Routes Broadcast 


A general broadcast through the Internet is achieved by setting the sa_netnum and 
sa_nodenum fields to binary ones (—1). The service provider translates this request to a 
type 20 packet, which IPX routers recognize and forward. The packet visits all subnets 
and may be duplicated several times. Receivers must handle several duplicate copies of 
the datagram. 


Use of this broadcast type is unpopular among network administrators, so its use should 
be extremely limited. Many routers disable this type of broadcast, leaving parts of the 
subnet invisible to the packet. 


Directed Broadcast 


Generally considered more network friendly than an all-routes broadcast, a directed 
broadcast limits itself to the local network that you specify. Fill sa_netnum with the target 
network number and sa_nodenum with binary ones. Routers forward this request to the 
destination network where it becomes a local broadcast. Intermediate networks do not 
see this packet as a broadcast. | 
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About Media Packet Size 


Media packet size affects the ability of IPX protocols to transfer data across networks 
and can prove challenging to deal with in a transport-independent manner. IPX does not 
segment packets, nor does it report when packets are dropped due to size violations. 
This means that some entity on the end station must maintain knowledge of the 
maximum packet size to be used on any given internetwork path. Traditionally, IPX 
datagram and SPX connection-oriented services have left this burden to the application, 
while SPXII has used Large Internet Packet negotiation to handle it transparently. 


Winsock attempts to set rational packet size limits for its various IPX protocols as 
described in the next section. These limits can be viewed and modified by applications 
through get/set socket options. When determining maximum packet size, the three areas 
of concern are: 


e # Media packet size 
e # Routable packet size 
e # End-station packet size 


Media packet size reflects the maximum packet size acceptable on any media the 
packet traverses to its destination. Packet size varies among differing media such as 
Ethernet and token ring. The amount of data space within a packet can also vary within 
a given media, depending on the packet header arrangement. For instance, the effective 
data size of an Ethernet packet varies eepencng on whether it is of the type Ethernet Il, 
Ethernet 802.2, or Ethernet SNAP. 


Routable packet size reflects the maximum packet size an intermediate router is willing 
to forward. Modern IPX routers are built to route any size datagram as long as it remains 
within the media size of the sending and receiving network. However, older routers may 
limit maximum packet size to 576 bytes, including protocol headers. 


End-station packet size reflects the size of the listen buffers that end stations have 
posted to receive incoming packets. Even when the media and router limits allow a 
packet through, it may be discarded by the end station if the receiving application has 
posted a smaller buffer. Many traditional IPX/SPX applications limit receive buffer size 
such that the data portion must be no larger than 512 or 1024 bytes. 


How Packet Size Affects Protocols 


Media packet size issues discussed in the topic, About Media Packet Size, affect the 
various PF_IPX protocols differently. A common strategy for handling various router and 
media size constraints is to use the full media size when the remote station’s network _ 
number matches the local station, and fall back to the minimum packet size otherwise. 


NSPROTO_IPX 
Provides a datagram service: each datagram must reside within the maximum 1 packet 
size. Winsock sets the maximum datagram packet size to the local media packet size 
minus the IPX header. Keep in mind, however, that if the packet is routed, it may hit 
router restrictions en route. Make sure your appiceton can fall back to 546-byte 
datagrams. 
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NSPROTO_SPX 


Provides stream and sequenced- packet services. Winsock IPX/SPX lets data streams 
and messages span multiple packets, so packet size does not limit the amount of data 
handled by send and recv. However, the underlying media size must be set correctly 
or the first large packet will be undeliverable and the connection will reset. If the target 
station is on the local network, Winsock sets its packet size to the media packet size. 
Otherwise, it defaults to 512 bytes. This size can be changed immediately after 


connect or accept through setsockopt. 


NSPROTO_SPXil 


SPXII features /arge Internet packet negotiation to maintain a best-fit size for packets 
and does not require programmer intervention. However, if the remote station does 
~ not support SPXII and negotiates down to standard SPX, the NSPROTO_SPxX rules 


are in effect. 


Protocol Media 
NSPROTO_IPX Ethernet 
Token Ring 


NSPROTO_SPX Ethernet 


Token Ring 


IPX/SPX Data Structures 


Type Data packet size 


Ethernet II 
802.3 
802.2 1466 


~ SNAP 


four megabit 

16 megabit 

Ethernet II 

802.3 

802.2 1454 
SNAP | 
four megabit 

16 megabit 


The IPX/SPX data structures in this section are MICroSOn: pepecilie implementations, and 


can be found in Wsnwiink. h. 


IPX_ADDRESS_DATA 


The IPX_ADDRESS_DATA structure provides information about a specific adapter to 
which IPX is bound. Used in conjunction with getsockopt function calls that specify 


IPX_ADDRESS in the optname parameter. 
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ses 


Eee Bs 


Members 


adapternum 
in] Adapter number. 


netnum | ee 
[out] IPX network number for the associated adapter. 


nodenum | Fate da a 
out] IPX node address for the associated adapter. | ? 


wan | | 
out] Specifies whether the adapter is on a wide area network (WAN) link. When 


TRUE, the adapter is on a WAN link. i : ee 


status ce 2°. a : 
out] Specifies whether the WAN link is up. FALSE indicates that the WAN link is up 
or the adapter is not on a WAN. Compare with wan to determine the meaning. 


maxpkt | 
[out] Maximum allowable packet size, excluding the IPX header. 
linkspeed 


[out] Link speed, returned in 100 bytes per second increments. For example, a 9600 
byte per second link would be return a value of 96. | a 


Remarks _— | 


Adapter numbers are base zero, so if there are eight adapters on a given computer, they — 
are numbered 0-7. To determine the number of adapters present on the computer, call | 
the getsockopt function with IPX_MAX_ADAPTER_NUM. | 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Wsnwlink.h. 
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getsockopt 


IPX_NETNUM_DATA 


The IPX_NETNUM_DATA structure provides information about a specified IPX network 
number. Used in conjunction with getsockopt function calls that specify 
IPX_GETNETINEFO in the optname parameter. 


netnum | 
[in] IPX network number for which information is being requested. 


hopcount 
[out] Number of hops to the IPX network being queried, in machine order. 


netdelay 
[out] Network delay tick count required to reach the IPX network, in machine order. 


cardnum 
[out] Adapter number used to reach the IPX network. The adapter number is zero 
based, such that if eight adapters are on a given computer, they are numbered 0-7. 


router 
[out] Media Access Control (MAC) address of the next-hop router in the path between 
the computer and the IPX network. This value is zero if the computer is directly 
attached to the IPX network. 


Remarks 


lf information about the IPX network is in the computer’s IPX cache, the call will return 
immediately. If not, RIP requests are used to resolve the information. 
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Version: Requires Windows Sockets 2.0. 
Header: Declared in Wsnwlink.h. 


IPX_SPXCONNSTATUS_DATA 


The IPX_SPXCONNSTATUS_DATA structure provides information about a connected 
SPX socket. Used in conjunction with getsockopt function calls that specify — 
IPX_SPXGETCONNECTIONSTATUS in the opitname parameter. All numbers in 
IPX_SPXCONNSTATUS_DATA are in Novell (high-low) order. 


Members 


ConnectionState 
Specifies the connection state. 


WatchDogActive 
Specifies whether watch dog capabilities are active. 


LocalConnectionid _ | 
Specifies the local connection ID. 7 : - 
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RemoteConnectionld 
Specifies the remote connection ID. 


LocalSequenceNumber 
Specifies the local sequence number. 


LocalAckNumber 
Specifies the local acknowledgment (ACK) number. 


LocalAllocNumber 
Specifies the local allocation number. 


RemoteAckNumber | 
Specifies the remote acknowledgment (ACK) number. 


RemoteAllocNumber | 
Specifies the remote allocation number. 


LocalSocket 
Specifies the local socket. 


immediateAddress | 
Specifies the IPX address to which the local computer is attached. 


RemoteNetwork 
specifies the network to which the remote host is attached. 


RemoteNode 
Specifies the remote node. 


RemoteSocket 
Specifies the remote socket. 


RetransmissionCount 
Specifies the number of retransmissions. 


| EstimatedRoundTripDelay | 


_ Specifies the estimated round trip—time delay for a given packet. 


RetransmittedPackets 
Specifies the number of retransmitted packets on the socket. 


SuppressedPacket | 
Specifies the number of suppressed packets on the socket. 


Ses 
: a 
o-- 


Version: Requires Windows Sockets 2.0. 
Header: Declared in Wsnwiink.h. 


getsockopt 


IPX/SPX Controls 


This section describes IPX/SPX socket options. 
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NSPROTO_IPX Socket Options 


NSPROTO_IPX options are handled through getsockopt and setsockopt. Each option 
is accessed by setting level = NSPROTO_IPX and optname to one of the following 


values. 

level = NSPROTO_IPX 

Option Type 
IPX_CHECKSUM Bool 
IPX_TXPKTSIZE int 
IPX_RXPKTSIZE int 
IPX._ TXMEDIASIZE int 
IPX_RXMEDIASIZE int 
IPX_ PRIMARY Bool 
level = NSPROTO_SPX 

Option Type 
SPX_CHECKSUM Bool — 
SPX_TXPKTSIZE _int 


Default 
off 


Media size to 
a maximum of 
1466 


Media size to 
a maximum of 
1466 


Primary board 


Primary board 


Primary 


Default 
off 


Media size to 
a maximum of 
1466 


Meaning 


When set, IPX performs a 
checksum on outgoing packets 
and verifies the checksum of 
incoming packets. 


Sets maximum send datagram 
size. This size does not include the 
IPX header or any media headers 
that may also be used. May be 
increased to media size. 


Sets maximum receive datagram | 
size. This size does not include the 
IPX header or any media headers _ 
that may also be used. May be 
increased to media size. 


Returns send media size that sets 
an upper bound for datagram size. 


Returns receive media size that 
sets an upper bound for datagram 
size. 


Restricts traffic to the primary 
network board. 


Meaning 


When set, IPX performs a 
checksum on outgoing packets. 
and verifies the checksum of 
incoming packets. Not supported 
on all platforms. | 


_ Sets maximum send datagram — 
_ size. This size does not include the 
SPX header or any media headers 


that may also be used. May be ~ 


Increased to media size. 


(continued) — 
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(continued) 
Option 
SPX_RXPKTSIZE 


SPX_TXMEDIASIZE 


SPX_RXMEDIASIZE 


SPX_RAWSPX 


SPX_RAWSPX 


Type Default | Meaning | 

int Media size to Sets maximum receive datagram 
amaximum of _ size. This size does not include the 
1466 SPX header or any media headers 


that may also be used. May be 
increased to media size. 


int Primary board Returns send media size minus 
SPX and media headers. This sets 
an upper bound for message 
segmentation packet size. 
int Primary board Returns receive media size minus 
| SPX and media headers. This sets 
an upper bound for receive packet 
size. 
Bool off When set, the IPX/SPX protocol 
: header is passed with the data. 


‘When set, SPX_RAWSPxX lets the application manage the IPX/SPX header. In this 
mode, Winsock will not segment messages, restricting maximum send and recv 
message size to the underlying packet size. Packet size options are automatically 
adjusted to include the IPX/SPX headers. Fields that can be set by the application are 


detailed in Wsipx.h. 


DECnet 


This section covers extensions to Windows Sockets 2 that are specific to DECnet. It also 
describes aspects of base Windows Sockets 2 functions that require special 
consideration or that may exhibit unique behavior. | 


Fast Facts 
Protocol name(s) 
Socket type 
Description 
Address family 
Header file 


DECnet Overview 


DNPROTO_NSP 
SOCK_SEQPACKET 
Provides transport service over the DECnet network layer. 


AF DECnet 


Ws2dnet.h 


The Digital Network Architecture (DNA) consists of an architectural overview and a set of 
specifications defining various network protocol layers. DECnet refers to a set of 
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products that implement the Digital Network Architecture. DECnet Phase IV, as 
introduced in 1982, supports peer-to-peer connectivity in both local and wide area 
networks. 


DNPROTO_NSP Protocol Family 


DECnet Phase IV uses Network Services Protocol (NSP) as its transport layer. 


AF DECnet Address Families 


The AF_DECnet Address families include: 


DECnet Phase IV Node Addresses 


~ DECnet Phase IV node addresses are hierarchical, indicating the routing area and the 
node number within that area. The binary format of the address is a 16-bit unsigned 
integer. The high-order 6 bits indicate the area, the low-order 10 bits are the node 
number within the area. 


The ASCII format of the address is area. number with area in the range 1-63, and 
number | in the range 1-1023. 3 


For example: A DECnet node address in area 5, number 7 is represented as shown in 
the following table. 


ASCIl format moe i 
Binary value | 000101 0000000111. 
Hexadecimal value 0x1407 


DECnet Extended Addressing 


DECnet extended addressing allows the DECnet NSP transport to be run over the OSI- 
routing layer. Sockets opened through AF_DECnet assumes that addresses of 3 to 20 
bytes | in length are OSI-style addresses. 


DECnet Objects 


DECnet client tasks specify the server task that they want to communicate with by using 
network object number and task names. The DECnet object number is an 8-bit unsigned 
value. Object numbers in the range 1-127 are reserved as generic objects for out 
use. Numbers 1-128 are available for user-written generic objects. | 


If the object number is zero, then the network connect is done to a specific server task 
name. Task names are 1—16-byte ASCII strings. 
#17 FAL Generic DECnet file access listener. 
#19 NME Generic DECnet network management listener. 
#0 DEBUG_TASK User-specified debug server task. 


DECnet sockets use sequenced packets that maintain message boundaries across the 


network. 
DECnet Data Structures 


insock and QOS 


SOCK_SEQPACKET Socket Type 
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rts 
ee 


ee 
oe 


ores 
pee 


ae 
ae 


oe 
e 


addr 
Pointer to a SOCKADDR_DN structure that receives the address of the connecting 
entity, as Known to the communications layer. 


Deferred Accept with Optional and Access Data 


DECnet sockets support both immediate and deferred accepts. It also supports the 
exchange of up to 16 bytes of optional data on accept and connect. It also supports the 
receipt of DECnet access control information by the server from the client on a connect 
request. a 7 e 


oe He 


. 
ie 
oe 
ee 
eee 


oe 


ae ae : es SOS ees 
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_DECnet optional data is passed in an OPTDATA_DN structure. Access control data is 
passed in an ACCESSDATA_DN structure. 


In the CALLBACK function, the /oCal/lerData should point to a CALLDATA_DN structure 
that contains concatenated OPTDATA_DN and ACCESSDATA_DN structures. If 
lpCallerData is set to NULL, no additional data will be read from the caller. If either the 
OPTDATA_DN.OPT_OPTL or the ACCESSDATA_DN.ACC_USERL are set to zero, 
that portion of the structure will be ignored. 


The accept only reads ACCESSDATA_DN, it does not write it, so only OPTDATA_DN 
can be returned by the server. The /pCalleeData pointer should point to a buffer 
containing the OPTDATA_DN structure. If |oCalleeData is set to NULL, no optional data 
can be read from the server. 


Structure Information for Bind/WSPBind 


In order to bind a local DECnet address to a socket, the parameter name should point to 
a SOCKADDR_DN structure. 


cee 
eee 


es 


SE 


ce 


name 
Pointer to a SOCKADDR_DN structure that contains the DECnet address to be 
bound to this socket. | 


Connections Using Connect/WSAConnect/WSPConnect 


This section provides connection information using Connect functions. 


Connect with no Optional or Access Data 


In order to establish a connection to a DECnet peer, the parameter name should point to 
a SOCKADDR_DN structure. 


se 
ee 


oe 


seo 


Bee ana 


683 


O 
© 5 
roe = 
O = 
3 i = 
= © oc © 
r= ” = 
< ”) ee ee 
2 2 oO 9 
= 3 c= 
8 S ae 
° S ¢ §& 
s On So 
2 Q Qn 
raw o 2 
o 
N = © 
x S oma) 
° fe nN @ 
7) Cc Oo - 
= — ® 
E 3 =e 
= = oO 
fe) © wi 
™ — ©; 
: Bo eg 
a i 2od 
5 Exo Dg ee 8 
Oo : 50 6 6UH®lUOUCOUCDS 
20. .9°7 2 
o5 O28 862 
oc Oo £26 
z°8 Oor Cc 
oc 2 oo 28g 
qe #£6&; 
A »w Sess 
a2 &5a5 
<o $290 
0:6. 2 028 
Ae Sanz 
o @eue 
Ce py wlos 
= : me 
© £©OWV5 
Fig. @8-o-¢ 2 
$2 sel. S6e 
eS £385 
So £6450 
af #0 
eau” o 
oascs 


ion 


t 


ip 
inter to the user data that 


Descri 
Po 


ter 


arame 


p. 


is to be transferred from the client to 


llerData 


IpCa 


ro) 
x 
— 
= 
O 
= 
~~ 
O 
wo 
fo) 
"™: -: 
® 
Eon 
O&O 
ee 
ec 8 
o = 
oO = 
©. § 
~ 5 
2 of 
2 cS 
§ 2 '9 
i 
om © 
oc Ss 
SF 
Oo ®& @ 
—- - * 
Oo Ce 
zo 8 
ce 8O 
Oo £ ® 
Oo 2¢ 
a) 
2B5 
= O 
J. 
oO o5 
So 
oe eS 
Oo @® 
San 
— & 
Q 
® 
a) 
O 
QO — 
Q 


d. 


is 
If JoCalleeData is set to NULL, no optional data will be read from the server. If either the 


tenated 


to NULL, no 
ignore 


t 


INS conca 


IS Sse 


Access control data 


lf JoCallerData 


additional data will be sent to the server. If either the opdata_dn.opt_optl or the 


DN structure 
DN structure that conta 


TA 


, that portion of the structure should be 
dn.acc_userl are set to zero, that structure should 


be ignored. The accept function only returns optional data, not access data. So the 


inan OPTDA 


d 
A_DN structure 


int to a CALLDATA 


OPTDATA_DN and ACCESSDATA_DN structures 


is passe 
O 


ti or the accessdata 


| data 
1/0 


lona 
t_o 


in an ACCESSDAT 


The /IpCallerData should p 
accessdata_dn.acc_userl are set to zero 


DECnet opt 
opdata_dn.op 


Volume 1 Winsock and QOS 
passed 


684 


g 3 : 7 

=| 

= = = ou 
= © S = 2 
” fo” a) wm Cc. 
z ® © => Oo 
Q .: _ Bees O <= 2 
me) es oS qo Dd 
qo OD = ‘O-3° 
Eo 2 @ Y 2 
a) oO c os 
A o @® oOo O — 1) 
Oo © ae Os 
s Sc Og 
o. S al 

o£ a 32 = no ~ 
a ® + © 
D> & ® YL 5 =$ 
co Qo = @Me 
Si ae oo 2 Sa 
8 G8 +. £8 
SS as? =3 Eo 
82 @qwee 62 O§ 
— © £ =: £D oO*.. 
fa BS FB of HD 
a5 & 22 Sf @ 
o © oC 2a 5 <= 
a ee a 
bs Bes : ag EQ 
ac 2x 19 Og 
5 @ O Q o i 
oe wo co” Q GS 53 
oo =o) SE Sos 
5 = 2 52 BEF 
2 = — we So) ED 
ES BSE O92 6 £2 
a2 MsSa o nl G 
UO GW Cos OC ® mea 
—~ + — — o. O 
aa 82 2° Seg 
® ® Oo =o £O ‘Ory 
CS 8 = EaO mH O 
GO TS oEg o ® oO 
QQ Gee S cron 


Chapter 12 Winsock 2 Protocol-Specific Annex 


name 
Pointer to a SOCKADDR_DN structure that will return the local name to which a 


DECnet socket is connected. 


Using Getsockopt/WSPGetSockOpt 


The SO_LINKINFO socket option returns a LINKINFO_DN structure containing the 
current state of the specified DECnet logical link. 


Ss 
Descriptor identifying socket 
level 7 
DNPROTO_NSP 
optname 
SO_LINKINFO 
optval - 
FAR * LINKINFO_DN structure 
optlen 
~ Sizeof(LINKINFO_DN) 
lpErrno 


Pointer to error code 


Return Values | | 
If no error occurs, WSPGetSockOpt returns zero and the LINKINFO_DN structure 
pointed to by optval contains the current transport segment size and logical link state. 


See the LL_* manifest constants for valid link states. Otherwise, a value of 
SOCKET_ERROR is returned, and a specific error code is available in /pErrno. 
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eee 


dnet_addr : 


The dnet_addr identifier converts an 
binary address. 


Specifies the address of a character string that contains a DECnet node address in 
the form a.n (area.node). For example, 9.440 is a DECnet Phase IV node number. 


Return Values ere 
dnet_addr returns a pointer to the DN_NADDR structure 


If successful, it returns a pointer to a DN_NADDR structure that contains a binary 


DECnet address. Applications should copy this data before issuing another dnet_addr 
call. Otherwise, it returns a NULL pointer. 


dnet_eof 
The dnet_eof identifier tests a DECnet socket for an end-of-file condition. 


Specifies DECnet socket to test. © | co op es 


Return Values | eee. o Poe : 
If the connection is still active (either in a running or connected state), it returns zero. If 
the connection is inactive,aoneisreturned. = | | | 
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dnet_getacc 


The dnet_getacc identifier retrieves local access control for incoming DECnet 
connections based on the specified user name. 


nacc 
Pointer to the incoming access control record. nacc.dac_username contains the user 


name. This ASCIZ character string has a maximum length of DN_MAXACCL. 


Return Values 


If successful, it returns a pointer to a DNET_ACCENT structure. Applications should 
copy this data before issuing another dnet_getacc call. Otherwise, it returns a NULL 


pointer. 


dnet_getalias 


The dnet_getalias identifier returns any default access control information associated 
with a specific node. 


The following ASCIZ strings are all valid returns: 


“node” 

“node/username” 
“node/username/password” 
“node/username/password/account” 
“node/username//account” 


node 
Pointer to the node name for which dnet_getalias should search. 


Return Values 


The call returns the address of a static buffer that contains the information from the local 
DECnet node database. Applications should copy this data before issuing another 
dnet_getalias call. 7 


dnet_htoa 


The dnet_htoa identifier searches the local node database. If it finds the node name for 
the specified node address, it returns a pointer to an ASCIZ DECnet name string. 
Otherwise, it returns an ASCIZ node address string. 
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add 
Specifies the address of a DN_NADDR structure that contains the node number for 


which to search. 


Return Values 


The function returns the address of a static buffer that contains the node string. This 
string must be copied before dnet_htoa is called again. 


dnet_ntoa 


The dnet_ntoa identifier converts a DECnet node address from binary to ASCIIZ format. 
It converts the pointer to a DN_NADDR to a string in the form 9.123, for example. 


add 
Specifies the address of a DN_NADDR structure that contains the node number to 
convert. 


Return Values 


The function returns a pointer to a static string that contains the node address. This 
string must be copied before dnet_ntoa is called again. 


getnodeadd 


The getnodeadd identifier returns the local node’s DECnet address. 


Return Values 


The function returns the address of a static DN_NADDR structure containing the local 
node’s DECnet address. Applications should copy this data before issuing another 
getnodeadd call. If DECnet is not installed, it returns a NULL pointer 


getnodebyaddr | | | | 
The getnodebyaddr identifier searches for a DECnet node name that matches a 
specified DECnet address. The address is a 16-bit binary DECnet address, where the 
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high 6 bits are the DECnet area number and the low 10 bits are the DECnet node 
number. DECnet Phase IV node names consist of one to six alphanumeric characters 
with at least one alphabetic character. 


addr 
Pointer to the address for which getnodebyaddr should search. 


len 
Length in bytes of the requested address (range DN_ADDL to DN_MAXADDL). 


type 
Address family of the address (AF_DECnet). 


Return Values 


The function returns a pointer to a static NODEENT_F structure. The application must 
copy this data before issuing another getnodebyaddr call. If the end of file is reached, a 
NULL pointer is returned. 


getnodebyname 


The getnodebyname identifier searches for a DECnet node address that matches the 
specified DECnet node name. DECnet Phase IV node names consist of one to six 
alphanumeric characters with at least one alphabetic character. 


name 
Pointer to an ASCIIZ node name for which to search. 


Return Values 


The function returns a pointer to a static NODEENT_F structure. The application must 
copy this data before issuing another getnodebyaddr call. If the end of file is reached, a _ 
NULL pointer is returned. 


etnodename 


The getnodename identifier returns the name of the local DECnet node. DECnet Phase 
IV node names consist of one to six alphanumeric characters with at least one 
alphabetic character. | 
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Return Values 


The function returns the address of a static string that contains the local node’s ASCIZ 
DECnet name, or a NULL pointer if DECnet is not installed. The maximum size for a 
returned string is DN_MAXNODEL. The application must copy this data before issuing 
another getnodename call. 


DECnet Header File 


Use Ws2dnet.h. 


Open Systems Interconnection (OSI) 


This section presents OSI-transport information in the following topics. 


OSI Introduction 


This section covers extensions to Windows Sockets 2 that are specific to OSI transports. 
It also describes aspects of base Windows Sockets 2 functions that require special 
consideration or that may exhibit unique behavior when used with OSI transports. 


Fast Facts 

Protocol name(s) TP4/CLNS, TP4/NULL, and so forth. 

Description Provides OSI transport services over OSI networking layer: 
CLTS for unreliable datagrams and COTS for reliable 
connection-oriented message streams. _ 

Address family AF_OSI 

Header file Ws2osi.h 


International Organization for Standardization (IOS) 


The International Organization for Standardization (IOS) produces a set of standards to 
facilitate interconnection of computer systems. The Open Systems Interconnection (OSI) 
Reference Model subdivides the set into a series of layers. Winsock allows an 
application to use OSI Transport protocols. 


Examples of OSI profiles that may be implemented are shown in the following table. 


OSI profile | Description 

TP4/CLNS Transport class four over Connectionless- mode Network Service 
TP4/NULL Transport class four over Null Network Service 

TPO/CONS | Transport class zero over Connection-mode Network Service 
NULL/CONS Null Transport over Connection-mode Network Service - 


TPO/TCP eee Transport class zero over TCP/IP (RFC 1006) 
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The OSI profile is designated either by the protocol parameter or the /poProtocolinfo 
parameter to the WSASocket API. The TP4/NULL profile is a subset of the TP4/CLNS 
profile and is selected by the addressing information. The default OSI profile is 
TP4/CLNS. 


An application must use the WSAPROTOCOL_INFO structure returned by 
WSAEnumProtocols to discover the services provided by a particular OSI profile. For 
example, not all OSI profiles support connect and disconnect data. 


OSI Expedited Data 


OSI protocols may support expedited data. Expedited data is not subject to the flow 
control procedures for normal data and may overtake normal data. 


ISO Qualified Data 


The ISO 8208/X.25 protocol supports qualified data. Qualified data is sent by using the 
WSAloctl function to mark the following data as qualified, and then using the normal 
Winsock send functions. Qualified data is received by using the WSAloctl function to 
wait for notification of qualified data, and then using the normal Winsock recv functions. 


ISO Reset 


The ISO 8208/X.25 protocol supports resets. A reset may be generated by using the 
WSAloctI function. Two bytes of reset data are permitted. These are interpreted as reset 
cause and reset diagnostic. For further details of this data see the X.25 specification. 


OSI Quality of Service 
The provider-specific parameters in the flow specification are encoded ina 
Type/Length/Data format to enable multiple parameters to be provided. 


For example ISO 8208/X.25 call facilities may be specified by using the type 
OSI_PARAM_ID_X25_CALL_FACILITY. 


Option Profiles 


OSI protocols typically have a large number of options. These options may include: 


e Preferred class 
e Alternative classes 
e Timers 
~e@ Checksums 
e Lifetime 
e Others 


An option profile name may be used to select a set of options available in a particular 
vendor’s OSI-protocol implementation. The Windows Sockets specification does not 
define the options that may be selected. 
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Option profile names are specified in the OSI address structure. If an option profile name 
is not specified, the OSI protocol uses its default option profile. 


Address Format 


Two address formats for the OSI protocol are defined in this section. The 
SOCKADDRB_TP format is retained for compatibility with Windows Sockets 1.1-OSI 


protocols. Windows Sockets 2 OSI protocols support the SOCKADDR_OSITP format. It 
contains: 


e A Transport Selector (TSEL). 
e Network Service Access Point (NSAP). 
e Sub Network address (SNPA). 


e Extended addressing information. 
e The option profile name. 


The SNPA follows the rules of the Sub Network in use. For example, an SNPA would 
contain a 6-byte MAC address followed by a 1-byte Link Service Access Point (LSAP) 
giving a 7-byte SNPA. 


Some X.25 protocols use connect user data to select the listening socket. The extended 
addressing information contains connect user data. This field must not be specified for 
other OSI protocols. 


The address structure also contains the option profile name. If the name length is zero, 
the default option profile is used. 


The TP4/NULL OSl-protocol profile is selected by using the TP4/CLNS protocol, 
selecting a zero-length NSAP, and specifying the MAC address and LSAP in the Sub 
Network address field. 


OSI Data Structures 


The following structure is used to encode the provider-specific parameters in the flow 
specification: 


OSI Controls 


This section describes OSI control features using loctls and socket options. 
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loctls | 

The following commands are available. 

Command Semantics 

SIO_OSI_X25_ Waits for an ISO 8208/X.25 reset to occur, and then returns 
GET_RESET_DATA the reset data associated with the reset. No input buffer is 


required. The 2 bytes of reset data are copied to the output 
buffer. The WSAENOPROTOOPT error code is indicated for 
service providers that do not support X.25 resets. 


SIO_OSI_X25_ Generates an ISO 8208/X.25 reset. No output bufferis 

GENERATE_RESET required, the 2 byes of reset data are obtained from the input 
buffer. The WSAENOPROTOOPT error code is indicated for 
service providers that do not support X.25 resets. 


SIO_OSI_X25_ Indicates that the next message sent using one of the send 
SEND_QUALIFIED functions, or WSASend, will be sent as qualified data. No 
buffers are required. It is not necessary to call this function 
for subsequent sends of the same message where the 
MSG_PARTIAL flag has been used. The 
~WSAENOPROTOOPT error code is indicated for service 
providers that do not support X.25-qualified data. 


SIO_OSI_X25_ | Waits until the next message that is received by the recv or 

GET_QUALIFIED WSARecv functions is ISO 8208/X.25-qualified data. This 
command only completes once for each message received, 
even if the MSG_PARTIAL flag is returned. The 
WSAENOPROTOOPT error code is indicated for service 
providers that do not support X.25-qualified data. 


socket Options 


The following socket options are supported for setsockopt and getsockopt. The Type 
identifies the type of data addressed by optval. 


level = SOL_SOCKET 
Value | Type Meaning 


~ SO_EXPEDITED 7 ~BOOL = Negotiates expedited data. 


SO_X25 —CONFIRM_ DELIVERY BOOL ISO 8208/X.25 aa confirmation. 


SO_ EXPEDITED 
This option is negotiated during connection establishment. The setsockopt function 
must be used before the connection is established to specify the proposed option. 
The getsockopt function may be used after the circuit has been established to 
retrieve the final negotiated option. See ISO 8073 for further details. 
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SO_X25_CONFIRM_DELIVERY 
This option controls the state of the Delivery Confirmation bit (D-bit) for X.25 
protocols. If the D-bit is set, end-to-end confirmation of data occurs. The 
SO_X25_CONFIRM_DELIVERY option may be used to change the state of the D-bit 
many times during the life of a connection. 


OSI Function Specifics 


This section describes provider-specific parameters for Quality of Service and lists the 
OSI header file. | 


Quality of Service | 

The provider-specific parameters in the flow specification are encoded in a 
Type/Length/Data format to enable multiple parameters to be provided. The 
OSISPECFLOWPARAM structure is used to encode the parameter. 


The following parameter type is defined. 
Parameter = Type | Meaning 


OSI_PARAM_ID_ u_char[] «ISO 8208/X.25 call facilities. 
X25_CALL FACILITY — i ie ) 


OSL PARAM ID. X25 | CALL_ FACILITY 
This parameter specifies the ISO 8208/X.25 call facilities to be ised: The format of 
the data is the same as is coded in an X.25 call request/call confirm packet. For 
further details see the X.25 specification. 


: OSI Header File 


Use ws2osi.h. | 


ATM-Specific Extensions 


This section presents information describing the Asynchronous Transfer Mode (ATM) 
specific extensions. | 


AT M Introduction 


This | section describes the Asynchronous Transfer Mode (ATM)-specific extensions 
needed to support the native ATM services as exposed and specified in the ATM Forum 
_ User Network Interface (UNI) specification version 3.x (3.0 and 3.1). This document 
supports AAL type 5 (message mode) and user-defined AAL. Future versions of this 
document will support other types of AAL as well as UNI 4.0 after it’s finalized. 
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Fast Facts 

Protocol name(s) | ATMPROTO_AAL5, ATMPROTO_AALUSER 

Description ATM AALS5 provides a transport service that is connection- 
oriented, message-boundary preserved, and QOS guaranteed. 
ATMPROTO_AALUSER is a user-defined AAL. 

Address family AF_ATM 

Header file Ws2atm.h 

verview 


ATM is an emerging high-speed networking technology that is applicable to both LAN 
and WAN arenas. An ATM network simultaneously transports a wide variety of network 
traffic—voice, data, image, and video. It provides users with a guaranteed quality of 
service on a per-virtual channel (VC) basis. 


ATM Data Structures 


A new address family, AF_ATM, is introduced for native ATM services, and the 
corresponding SOCKADDR structure, sockaddr_atm, is defined in the following. To 
open a socket for native ATM services, parameters in socket should contain AF_ATM, 
SOCK_RAW, and ATMPROTO_AAL5 or ATMPROTO_AALUSER, respectively. 


Members 


satm_family 
Identifies the address family, which is AF_ATM in this case. 


satm_number 
Identifies the ATM address that could be either in E.164 or NSAP-style ATM End 
Systems Address format. See Using the ATM_ADDRESS Structure for more details 
about the ATM_ADDRESS structure. This field will be mapped to the Called Party 
Number IE (Information Element) if it is specified in bind and WSPBind for a listening 
socket, or in connect, WSAConnect, WSPConnect, WSAJoinLeaf, orWSPJoinLeaf 
for a connecting socket. It will be mapped to the Calling Party Number IE if specified 
in bind and WSPBind for a connecting socket. 


satm_blli | | 
Identifies the fields in the B-LLI Information Element that are used along with 
satm_bhli to identify an application. See the Using the ATM_ADDRESS Structure 
section for more details about the ATM_BLLI structure. Note that the B-LLI layer two 
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information is treated as not present if its Layer2Protocol field contains 
SAP_FIELD_ABSENT, or as a wildcard if it contains SAP_FIELD_ANY. Similarly, the 
B-LLI layer three information is treated as not present if its Layer3Protocol field 
contains SAP_FIELD_ABSENT, or as a wildcard if it contains SAP_FIELD_ANY. 


satm_bhli 
Identifies the fields in the B-HLI Information Element that are used along with 
satm_blli to identify an application. See Using the ATM_ADDRESS Structure for 
more details about the ATM_BHLI structure. 


Note Satm_bhli is treated as not present if its HighLayerInfoType field contains 
SAP_FIELD_ABSENT, or as a wildcard if it contains SAP_FIELD_ANY. | 


For listening sockets, the SOCKADDR_ATM structure is used in bind/WSPBind to 
register a Service Access Point (SAP) to receive incoming connection requests destined 
to this SAP. SAP registration is used to match against the SAP specified in an incoming 
connection request in order to determine which listening socket is to receive this request. 
In the current version of this specification, overlapping registration is not allowed. 
Overlapping registration is defined as having more than one registered SAP to 
potentially match the SAP specified in any incoming connection request. Listen and 
WSPListen will return the error code WSAEADDRINUSE if the SAP associated with the 
listening socket overlaps with any currently registered SAPs in the system. 


The fields in a SAP to be registered must contain either a valid value, or one of two 
special manifest constants: SAP_FIELD_ABSENT or SAP_FIELD_ANY. 


SAP_FIELD_ABSENT simply means that this field is not presented as part of a SAP. 
SAP_FIELD_ANY means using wildcards. 


Note that the requirement of nonoverlapping registration does not preclude using 
wildcards. For example, it is possible to have two registered SAPs that both contain 
SAP_FIELD_ANY in some fields and different values in other fields. 


Note The called party ATM number is mandatory, thus the satm_number field cannot 
contain SAP_FIELD_ABSENT. 


For connecting sockets, the SOCKADDR_ATM structure is used to specify the 
destination SAP in connect/WSAConnect/WSPConnect for point-to-point connections, 
and WSAJoinLeaf/WSPuJoinLeaf for point-to-multipoint connections. The fields in the 
destination SAP of a connecting socket must contain either a valid value or 
SAP_FIELD_ABSENT, that is, SAP_FIELD_ANY is not allowed. 


Furthermore, SAP_FIELD _ABSENT i is not allowed for the satm_number field. The 
destination SAP is used to match against all the registered SAPs in the destination 
machine to determine the forwarding destination for this connection request. If each and 
every field of the destination SAP of an ene isu either equals the 
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(continued) 


Parameters 


Layer2Protocol | | ? 
Identifies the layer-two protocol. Corresponds to the User information layer 2 protocol 
field in the B-LLI information element. A value of SAP_FIELD_ABSENT indicates that 
this field is not used, and a value of SAP_FIELD_ANY means wildcard 


Layer2UserSpecifiedProtocol  =—> 2 
Identifies the user-specified layer-two protocol. Only used if the Layer2Protocol 
parameter is set to BLLI_L2_ USER_SPECIFIED. The valid values range from zero— 


127. Corresponds to the User specified layer 2 protocol information field in the B-LLI 
information element. | 3 


Layer3Protocol | 
Identifies the layer-three protocol. Corresponds to the User information layer 3 
protocol field in the B-LLI information element. A value of SAP_FIELD_ABSENT 
indicates that this field is not used, and a value of SAP_FIELD_ANY means wildcard. 


Layer3UserSpecifiedProtocol } 
Identifies the user-specified layer-three protocol. Only used if the Layer3Protocol 
parameter is set to BLLI_LL3_ USER_SPECIFIED. The valid values range from zero— 
127. Corresponds to the User specified layer 3 protocol information field in the B-LLI 
information element. 


Layer3IPI eg 
Identifies the layer-three Initial Protocol Identifier. Only used if the Layer3Protocol 
parameter is set to BLLI_L3_ISO_TR9577. Corresponds to the ISO/IEC TR 9577 
‘Initial Protocol Identifier field in the B-LLI information element. 7 


SnapI|D | : : 
Identifies the 802.1 SNAP identifier. Only used if the Layer3Protoco! parameter is set 
to BLLI_L3_ISO_TR9577 and Layer3IPI is set to BLLI_L3_IPI_SNAP, indicating an 
IEEE 802.1 SNAP identifier. Corresponds to the OU/ and PID fields in the B-LLI 
information element. 
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ATM_BHLI Structure and Associated Manifest Constants 


Parameters 
_ HighLayerlnfoType | care 7 


Identifies the high layer information type field in the B-LLI information element. Note 
that the type BHLI_HighLayerProfile has been eliminated in UNI 3.1. A value of 
SAP_FIELD_ABSENT indicates that B-HLI is not present, anda value of 


SAP_FIELD_ANY means wildcard. 


HighLayerlnfoLength | 
Identifies the number of bytes from one to eight in the HighLayerinfo array. Valid — 
values include eight for the cases of BHLI_ISO and BHLI_UserSpecific, four for 
BHLI_HighLayerProfile, and seven for BHLI_VendorSpecificAppld. 


HighLayerInfo 
Identifies the high layer information field in the B-LLI information element. In the case 
of HighLayerinfoType being BHLI_VendorSpecificAppld, the first 3 bytes consist of a 
globally-administered Organizationally Unique Identifier (OUI) (as per IEEE standard 
02-1990), followed by a 4-byte application identifier, which is administered by the 
vendor identified by the OUI. Value for the case of BHLI_UserSpecific is user defined 
and requires bilateral agreement between two end users. — : 


ATM Controls | 


ATM point-to-point and point-to-multipoint connection setup and teardown are natively 
supported by the Windows Sockets 2 specification. In fact, Windows Sockets 2 QOS 
specification and protocol-independent multipoint/multicast mechanisms were designed 
with ATM in mind, along with other protocols. See section 2.7 and appendix D of the 
Windows Sockets 2 API specification for Windows Sockets 2 QOS and multipoint 
support, respectively. Therefore, no ATM-specific ioctls need to be introduced in this 
document. | | | 
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ATM Function Specifics 


Based on the taxonomy defined for Windows Sockets 2 protocol- independent 
multipoint/multicast schemes, ATM falls into the category of rooted data and rooted 
control planes. (See the Windows Sockets 2 API specification, Appendix D for more 
information.) An application acting as the root would create c_root sockets, and 
counterparts running on leaf nodes would utilize c_leaf sockets. The root application will 
use WSAJoinLeaf to add new leaf nodes. The corresponding applications on the leaf 
nodes will have set their c_leaf sockets into the listening mode. WSAJoinLeaf with a 
c_root socket specified will be mapped to the Q.2931 SETUP message the first ia 
or ADD PARTY message (for any subsequent leaves). 


Note The QOS parameters specified in WSAJoinLeaf for any subsequent leaves 
should be ignored per the ATM Forum UNI specification. 


The leaf-initiated join is not part of the ATM UNI 3.1, but is supported in the ATM 
UNI 4.0. Thus WSAJoinLeaf with a c_leaf socket specified can be mapped to the 
appropriate ATM UNI 4.0 message. 


The AAL Parameter and B-LLI negotiation is supported through the modification of the 
corresponding IEs in the |pSQOS parameter upon the invocation of the condition 
function specified 1 in WSAAccept. 


Note Only certain fields in those two IEs can be modified. See the ATM Forum UNI 


— specification Appendix C and Appendix F for details. 


ATM-Specific Quality of Service Extension 


This section describes the protocol-specific Quality of Service (QOS) structure for ATM, 
which is contained in the ProviderSpecific.buf field of the QOS structure. Note that the 
use of this ATM-specific QOS structure is optional by Windows Sockets 2 clients, and 
the ATM service provider is required to map the generic FLOWSPEC structure to 
appropriate Q.2931 Information Elements. However, if both the generic FLOWSPEC 
structure and ATM-specific QOS structure are specified, the value specified in the ATM- 
specific QOS structure should take precedence should there be any conflicts. See 
Windows Sockets 2 API specification section 2.7 for more information about the QOS 
provisions and FLOWSPEC structure. 


The protocol-specific QOS structure for ATM is a concatenation of Q.2931 Information 
Element (IE) structures, which are defined in the following text. If an application omits an 
IE that UNI 3.x mandates, the service provider should insert a reasonable default value, 


_ taking the information in the FLOWSPEC structure into account if applicable. 


The handling of repeated IEs is dependent on the IE itself. If an IE is repeated and it is 
one that is allowed to be repeated per the ATM Forum UNI specification then the 
provider must handle it properly. In this case, order in the list determines preference 
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Broadband Bearer Capability 


This section lists the values used for the Broadband Bearer Capability. 
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ATM Header File oF 


Use ws2atm.h. 


Other Windows Sockets 2 Considerations 
Secure Sockets Layer (SSL) 


Secure Sockets Layer (SSL) is not natively supported in Windows Sockets 2. Microsoft 
makes available the Security Support Provider Interface (SSPI) to enable application 
programmers to provide security-enabled communications. See the section titled 

_ Security Support Provider Interface (SSPI), found under Security in the Platform SDK, 
for more information. 


RSVP eet, 
The Resource Reservation Protocol (RSVP) implementation of the Windows Sockets 2 
Protocol-Specific Annex, found at 
-_ ftp://ftp.microsoft.com/bussys/winsock/winsock2/wsanx203.doc, is supported by 
_ Microsoft through Windows 2000 QOS functionality. For more information on RSVP in 
Windows 2000, check following chapters in this volume of the Networking Services 
Developer's Reference Library. 
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CHAPTER 18 


QOS Overview 


QOS Documentation Structure 


To facilitate explanation, Windows 2000 Quality of Service (QOS) documentation divides 
its QOS components into three categories: 


e Application-Driven QOS Components 
¢ Network-Driven QOS Components 
e Policy-Driven QOS Components 


This division is purely for the sake of convenience and clarity. Though each of these 
QOS components is in some way initiated at the client or end-node, and in pure 
semantics, is initiated by the application, the impact of the component may actually be 
greatest elsewhere. 


For an example (which may be clearer once the 802.1p QOS component is further 
explained), the 802.1p precedence bits are actually set in the end-node’s network stack. 
This is done because it was an application-initiated sequence of QOS events that 
eventually triggered the setting of the bits. The cause of this bit-setting, then, could be 
argued to be the application’s initiation of QOS service (thus application-driven). 
However, because the effect of setting the priority on 802.1p bits has the greatest impact 

_ when the packets associated with this session cross their local segment, 802.1p is | 
included in the Network-Driven QOS Components category, but not in the Application- 
Driven QOS Components category. Despite the fact that no QOS requests would have 
been instigated to set the 802.1p bit without the application’s invocation of a QOS 
component, its explanation is best placed in a discussion of network-driven components. 
The ripple-effect of 802.1p bit setting, then, is felt greatest in the network. 


Although individual components from among the three categories can function 
~ independently at times to provide subsets of QOS functionality, Windows 2000 QOS 
overall is an integrated technology. 


Figure 13-1 provides a visual representation of the structure of QOS documentation, and 
the reasoning behind its structure; certain QOS components have greatest impact in one — 
of the three categories, and are thus discussed there. 
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Windows 2000 QOS components facilitate predictable quality of service for interaction between two devices. 


Application-Driven = RSVP enabled Routers 
QOS Components’ 


areas of greatest impact ‘ 7 
(darkly shaded areas) Network-Driven wee = Interfaces to distant subnets 


QOS Components’ 
area of greatest impact 
(medium shaded area) 


Policy-Driven QOS 
Components’ area of 
greatest impact 
(lightly shaded area) 


Figure 13-1: Visual Representation of QOS Documentation. 


Determining Which Discussion Is for You 


Most developers of QOS-enabled applications will find their requirements met within the 
QOS API, and the requisite knowledge of componenis will fall largely under the 
Application-Driven QOS Components section. Thus, reading through that overview 
material, combined with the API reference information in QOS Reference, should provide 
nearly all of the information necessary to develop QOS-aware applications. 


There is more information in other sections of QOS documentation that facilitates the 
development of granular Traffic Control. For example, that found in the Network-Driven 
QOS Components section, can provide explanations of the underlying technologies and 
programmatic reference to interfaces available for such efforts. In such circumstances, a 
reading of the Application-Driven and Network-Driven sections is suggested. 


For development of policy module components, such as policy-based decision services 
intended to provide network resource—admission services, the Policy-Driven sections are 
recommended. 


For a complete understanding of QOS and its components, as they are implemented and 
interact within the Microsoft® Windows 2000® (and Microsoft® Windows® 98) 
framework, reading all of the overview sections is recommended. 
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Additional Information on QOS 


For additional information on Windows 2000 Quality of Service, including implementation _ 
recommendations and approaches, the following book is available: 


Iseminger, David, Windows 2000 Quality of Service, (Macmillan Technical 
Publishing, 1999). 


About Quality of Service 


Quality of Service in Microsoft® Windows® 2000 is a collection of components that 
enable differentiation and preferential treatment for subsets of data transmitted over the 
network. QOS components constitute the Microsoft implementation of Quality of Service. 


Quality of Service is a defined term that loosely means subsets of data get preferential 
treatment when traversing a network. QOS technology has implications for the 
application programmer and the network administrator. 


By writing QOS-enabled applications, programmers can: 


e Specify or request bandwidth requirements particular to their application, such as 
latency requirements for streaming audio. 


e Write mission-critical applications for the corporate environment that are guaranteed 
to get their required ope ee permissions and bandwidth availability 
exist. 


Just as importantly, network administrators can leverage knowledge of Quality of 
Service to: 


- @ Control network device resources based on user policy and/or application usage. 


e Provision portions of a given bandwidth, whether an Ethernet subnet or a WAN 
interface, for applications or users that require such availability for core business 
activities. 


e Shape and smooth the traffic that clients submit to the network, thereby avoiding the 
sevemtiaeniid of switches and routers suffered with traditional burst transmissions. 


Windows 2000 Quality of Service achieves this through programmatic interfaces: the 
cooperation of multiple components, and communication with REHWON devices 
_ throughout the end-to-end network solution. 


Introduction to Qos 


if you've ever endured demonstrations of new software touting real-time audio and video 
to the desktop (gobbling megabits per second on the already-taxed network resources), 
only to find your important file transfer inching along, you may be interested in Quality of 
Service. If you’re the network administrator, ft, charged with ensuring that mission- critica 
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applications have sufficient bandwidth to keep the company functioning, while users 
flood the network with multimedia application data, you, too may be interested in Quality 
of Service. 


Quality of Service Defined 


Quality of Service is an industry-wide movement that aims to get more efficient use out 
of network resources by differentiating between subsets of data. The IETF (Internet 
Engineering Task Force) has played a central role in ensuring that QOS standards 
enable all affected network devices to participate in the end-to-end QOS-enabled 
connection. 


Quality of Service provides applications (or network administrators) with a means by 
which network resources—such as available bandwidth and latency—can be predicted 
and managed on both local computers and devices throughout the network. 


With such an all-network encompassing definition, QOS functionality requires 
cooperation among end nodes, switches, routers, and wide area network (WAN) links 
through which data must pass. Without some level of cooperation among those network 
devices, the quality of data transmission services can break down. In other words, if 
each such network device is left to make its own decisions about transmitting data, it 
would likely treat all data equally, and thus provide service on a first come-first served 
basis. Although such service may be satisfactory in network devices or transmission 
media that are not heavily loaded, when congestion occurs, such service can delay all 
data. With this information, we can extend the definition of quality of service—it allows 
preferential treatment for certain subsets of data as they traverse any QOS-enabled part 
of (or devices in) the network. 


Microsoft® Windows 2000® implements quality of service by including a number of 
components that can cooperate with (or invoke) one another. These components are 
found in the DLLs, protocols, services, and individual network device functionality. 


Windows 2000 Quality of Service Defined 


The Microsoft implementation of Quality of Service enables developers to use generic 
Windows Sockets 2 calls to create QOS-enabled applications. With the Windows 2000 
QOS capabilities, developers do not need to consider how the various operating system 


~ components interact to achieve quality of service. The components that constitute QOS 


implementation are instead abstracted from the QOS application development effort, 
allowing a single or generic QOS interface—instead of individual interfaces—for each 
QOS component. This provides a generic interface for the developer, and also provides 
a mechanism by which new QOS components (perhaps with increased functionality) can 
be added, without the need to completely rewrite existing QOS applications. | 


What QOS Solves 


As computing and applications become more mission-critical, not to mention more 
content-rich and multimedia-oriented, the bandwidth necessary to service desktop 
functionality increases. However, bandwidth availability doesn’t necessarily keep up with 
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the bandwidth appetite of today’s desktop applications, creating an environment where 
there is often more data to be transmitted than there are resources to transmit. The 
bursty nature of network transmissions only aggravates the problem. 


Traditional data transfers are also increasing as a result of the continual addition of new 
network nodes to existing networks. At the crux of this problem is the fact that there is no 
inherent means of differentiating between important data—such as data transmitted by 

_ mission-critical applications, and excessive data, or data transmitted by ieresting (but 
not necessarily critical) multimedia applications. 


Such traditional business applications are continuing to increase in size and in network 
use, but they aren't alone in their hunger for network resources. New applications such 
as multimedia applications, make extensive use of the network, pushing network 
utilization to its limit—and sometimes beyond. For example, video transmission 
applications require significant bandwidth to transmit with acceptable levels of quality. 
Due to the send-as-much-data-as-you-can nature of the most common networking 
protocol, IP, even a few active instances of these data-intensive programs can create 
bandwidth strain for networks that were never designed to carry the burden. With data- 
intensive multimedia applications putting such hefty data loads onto the network, the 
network often becomes less available for other applications. If the load is significant 
enough, overall network performance will wane. 


Poor network performance is especially threatening to real-time audio and interactive 
conferencing transmissions; they are time-sensitive and especially susceptible to delays 
or individual frame drops delivery. Such delays in the delivery of individual packets, 
known as /atency, can render real-time audio and real-time conferencing applications 
substandard at best and at worst, burdensome. 


In the midst of larger traditional applications’ higher network utilization, as well as _ 
increased network use by emerging desktop applications, core business applications are 
left vying, sometimes unsuccessfully, for adequate access to the network. These 
bandwidth-poor and latency-laden characteristics of an overburdened network have an 
even larger and more dramatic effect on mission-critical applications’ use of new 
multimedia desktop technology: not only do they need access to the burdened network, 
they need more of the increasingly precious network resources, putting core business 
applications that use multimedia features in double jeopardy. 


If such over-subscription of available network resources isn’t a bleak enough picture, 
consider the prevalence of WAN, which introduces an even more critical and more 
precious bandwidth restriction at the WAN link. With this, the situation is exacerbated. 


Mechanisms that manage network activity from an end-to-end perspective are needed to 
- manage over-subscription of network resources, to regulate the allocation of their 
availability, and to present network data in a means more friendly to a shared network 
environment (that is, in a less bursty manner). These mechanisms are found in 

Windows 2000 Quality of Service. 
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How Windows 2000 QOS Works 


To achieve manageable and predictable quality of service from one end of the network 
to the other, the collection of components that must communicate and interact results in 
a fairly complex process. Microsoft® Windows 2000 QOS has the ability to facilitate 
priority along every step of a packet’s journey: in the sender’s network stack, at the 
switch, and even at each QOS-enabled router hop. Quality of Service also has the ability 
to facilitate how much data can and should be sent in a given unit of time, maximum 
burst rates, and overall bandwidth utilization rights. These can be configured based on 
administratively configurable policies. These functional capabilities only scratch the 
surface of quality of service. 


Windows 2000 QOS is comprised of a number of components. Figure 13-2 shows where 
many of the QOS components reside in relation to the network stack, where 
communication occurs between and among them, and where certain interfaces, such as 
APIs, facilitate developing QOS services. 


Note that this is an individual node’s network stack view, not a functional schematic of 
how Quality of Service operates over a given network. Some of these components have 
further defined subcomponents, each of which is explained under Components. 


Windows 98 QOS Notes 


The following list describes Windows 2000 QOS caine not available in 
Microsoft® Windows® 98: 


Error Code Granularity 


Windows 98 does not support the fine-grained error codes that can be provided in 
ExtendedStatus1 and ExtendedStatus2. 


Kernel Traffic Control 
Kernel traffic control is not available in Windows 98. Therefore, observe the following 
restrictions when using Windows 98: 


Applications should not pass down or retrieve traffic objects, including shaping rage 
or shape/discard objects. 


The SERVICE_NO_TRAFFIC_CONTROL control flag is not available. 
~ADSPEC parameters specific to traffic control are not set. | 
Registry Parameters 
Windows 98 does not support the following registry parameters: 
EnablePriorityBoost 
EnableRSVP 
EnableSPSetIPTOS 
RSVP_RESERVE_INFO | | 
Windows 98 does not support the passing of RSVP_POLICY_INFO objects in the 
RSVP_RESERVE_INFO structure. 
Policy Objects 


Windows 98 does not support the submission or retrieval of application 
specific-policy objects. 
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Figure 13-2: QOS Components. 


Service Types _ 3 | 
The SERVICE_NO -Q0S_ SIGNALING control flag i is not available. 


SIO_CHK_QOS | 
Windows 98 does not support SIO_ CHK QOS, and as a result, Windows 98 does not 


support queries for AALOWED_TO_SEND_DATA, ABLE. _TO_RECV_RSVP, or 
~LINE_RATE. 
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SIO_SET_QOS 
Asynchronous calls to WSAloctl(SIO_SET 08) are not supported in Windows 98. 


TOS 
The RSVP service provider does not set Type of Service (TOS) bits in the IP header. 
TOS has been obviated by DSCP. 


Known QOS Issues 
The following are known issues regarding the use of Quality of Service on Windows 98. 


Socket Handles 

With Windows 2000 or Windows 98, if a QOS-enabled application passes socket 
handles between different processes and requests for QOS notifications on that socket, 
the application may receive multiple notification events. 

Overlapped I/O 


The use of overlapped I/O on a blocking socket for QOS event notification is 
problematic. 


QOS Header Files 


Certain QOS-specific data structures should not be used in Windows 98. The following 
list outlines those structures. 


ABLE_TO_RECV_RSVP SERVICETYPE_NONCONFORMING 
ALLOW_TO_SEND_DATA _ TC_NONCONF_BORROW 
INFO_NOT_AVAILABLE TC_NONCONF_SHAPE 

LINE RATE : TC_NONCONF_DISCARD 
QOS_OBJECT_SD_MODE TC_NONCONF_BORROW_PLUS 


RSVP_OBJECT_POLICY_INFO 


Q0S Components 


To facilitate explanation, the Microsoft® Windows 2000 QOS documentation divides the 
QOS components into the following three topics: 


e Application-Driven QOS Components 
e Network-Driven QOS Components 
e Policy-Driven QOS Components 


Note This segmentation is purely for convenience and clarity. Though individual 
components among the three categories can function independently to provide certain 
subsets of QOS functionality, overall, Windows 2000 QOS is an integrated technology. 
For more information on how the documentation is organized, see QOS Documentation 
Structure. 


Chapter 13 QOS Overview 721 


This is the approach taken with all QOS components, with one exception: RSVP. 
Though the bulk of RSVP will be discussed within the Application-Driven QOS 
Components topic, elements that have effects elsewhere (namely in the network, and for 
facilitation of policy checking) will be included in their respective sections. 


Application-Driven QOS Components 


RSVP Service Provider 
The RSVP service provider facilitates Windows 2000 QOS and invokes other 
QOS components. 


Traffic Control Modules 
Traffic control modules facilitate traffic control. Traffic control modules include the 
packet classifier, the packet scheduler, and the packet shaper. 


Resource Reservation Protocol (RSVP) Service 
Resource ReSerVation Protocol is invoked by the RSVP SP, and the carrier of RSVP 
messages across the entire network, with a functional interface for each QOS- 
enabled network device hop across the network. Though important to overall 
Windows 2000 QOS technology, and to QOS in general, certain QOS faculties do not 
require RSVP to operate, which means that quality of service can be achieved without 
RSVP signaling. 


QOS API 
The QOS API is the programmatic interface to the RSVP SP. 


Traffic Control API (TC API) ? 
The traffic control API is a programmatic interface to the traffic control components 
that regulate network traffic on local hosts. | : 


QOS API 


The QOS API is the programmatic interface to the RSVP service provider (RSVP SP). 
Under most circumstances, the QOS API is the only interface that programmers will 
require to create QOS-aware or QOS-enabled applications. Most operations that happen 
on behalf of an application in the QOS sequence are a result of QOS API calls 
communicating requests down (and sometimes back up) through QOS components, 
creating a QOS-enabled flow of data that keeps important data moving through the 
network with preferential transmission consideration. 


For more information on the programming elements included in the Qos API, see 
QOS Reference. 


RSVP Service 


The RSVP service is a single instance Windows 2000 service that runs on a 
Windows 2000 computer. The RSVP service instigates traffic control functionality 
(if appropriate), and implements, maintains, and handles RSVP signaling for all 
Windows 2000 QOS functionality. 


The RSVP service, by virtue of the fact that it implement and maintains RSVP and is 
the initiator of traffic control, is at the heart of Windows 2000 Quality of Service. 
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RSVP Service Provider 


The RSVP service provider (RSVP SP) is the name for the QOS component that invokes 
nearly all resulting QOS facilities. The RSVP SP communicates Windows Sockets 2 
QOS semantics to the RSVP SP. The Rsvpsp DLL is loaded by Windows Sockets when 
a QOS-enabled socket is opened. 


Traffic Control API 


The traffic control application programming interface (TC API), is a programmatic 
interface to the components that regulate network traffic on local hosts; both from an 
internal perspective (within the kernel itself), and from a network perspective 
(prioritization and queuing of packets based on transmission priority). 


Traffic control is implicitly invoked through calls made to the QOS API and subsequently 
serviced by the RSVP service provider (RSVP SP). However, applications that require 
further or specific control over traffic control can use the TC API. The RSVP Service also 
uses TC API calls. 


Note that the use of functions in the TC API requires administrative privilege. 


Traffic Control and Differentiated Services 


Windows 2000 QOS is capable of providing differentiated services. The traffic control 
functionality built into Microsoft Windows 2000 QOS is also capable of operating in 
differentiated services mode. This capability is primarily used on routers, in which 
incoming IP packets are classified into generalized (differentiated) flows using the 
Diffserv code point (DSCP), rather than setting up and monitoring individual RSVP flows. 


The packet scheduler component of TC can be put into differentiated services mode for 
a given interface by: 


e Using TcSetinterface, Set GUID_QOS_ADAPTER_MODE to 
PSADAPTER_FLOW_MODE_DIFFSERV 


The interface can be returned to its default mode of operation by setting the GUID to the 
default value of PSADAPTER_FLOW_MODE_STANDARD. 


While operating in Diffserv mode, standard TC function calls, such as those found in the 
Traffic Control API (TC API) section are still used, but a special QOS object called 
QOS_OBJECT_DIFFSERV can be included with the TcAddFlow function call. This 
QOS object is used to specify the list of DSCPs that are used to classify incoming IP - 
packets on a given flow. Hence the TcAddfilter function and TeDeleteFilter function will 
not be used for classifying packets. 


For more information about QOS_OBJECT_DIFFSERV, see QOS Objects. 
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Traffic Control Modules 


Traffic control (TC) plays a central role in the provision of quality of service. With traffic. 
control, packets are prioritized both inside and outside the node on which TC is used. 
The implications for such granular control (or preferential treatment) of packets as they 
flow through the system and through the network, reach across the entire network realm 
or enterprise. Traffic control is realized through two modules, the Generic Packet 
Classifier and the Packet Scheduler. | 


Generic Packet Classifier 


Packet classification provides a means by which packets internal to a specific network 
node can be classified, and consequently prioritized, within and by both user and kernel- 
mode network components. These classification and prioritization uses include activities 
such as CPU processing attention or transmission onto the network. The Generic Packet 
Classifier (GPC) is utilized through the Generic Packet Classifier Interface, or GPC 
Interface, which facilitates an information store that can be used or associated with 
specified (defined) subsets of packets. 


The importance of GPC hinges on its ability to provide lookup tables and classification 
services within the network stack, and is thus the first step in an overall and ubiquitous © 
prioritization scheme for network traffic. 


Packet Scheduler 


Packet scheduling is the means by which data (packet) transmission-governing—a key 
function of quality of service—is achieved. The packet scheduler is the traffic control 
module that regulates how much data an application (or flow) is allowed, essentially 
enforcing QOS parameters that are set for a particular flow. The packet scheduler 
incorporates three mechanisms in its scheduling of packets: : 


e A conformer 
e The packet shaper 
e A sequencer 


The conformer and sequencer are discussed in more detail in the traffic control 
documentation. Since the packet scheduler’s role is essential to overall traffic control 
understanding, it is defined here. | : 


The packet scheduler considers the classification provided by the Generic Packet 
Classifier (GPC), and provides preferential treatment to higher-priority traffic. 
Consequently, the packet scheduler is the first step (in a sequential view) to ensuring 
that the prioritized network transmission of packets Hegiis ile data that has been 
‘deemed most important. — | : 


Part of the packet scheduler’s responsibility is shaping the way packets are tranismitied 
from a network device, a capability often referred to as packet shaping. Though often 
referenced by its own name, the packet shaper is simply a part of overall packet 
~ scheduler functionally. | 
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The packet shaper mitigates the burst nature of computer network transmissions by 
smoothing transmission peaks over a given period of time, thereby smoothing out 
network usage to affect a more steady use of the network. The significance of the packet 
shaper becomes apparent: one factor that contributes to network congestion is the burst 
nature of computer data transmissions, a side-effect of the inherent “send it all out right 
now” nature of IP transmission. Packet shaping can help alleviate at least some of the 
effects of such activity by spacing out QOS-enabled packet transmissions. 


Network-Driven QOS Components 


802.1p 
The use of flags in the Media Access Control (MAC) header to establish packet 
priority in shared-media 802 networks. 


Differentiated Services 
Enables the marking of relative priority for IP packets. Differentiated Services enable 
the marking of packets with a code point value, called the DiffServe code point, which 
is used by network devices such as routers to determine the Per-Hop Behavior (PHB) 
treatment to which the packet is subjected. Essentially, differentiated services 
specifies a packet's transmission priority as it passes through each network device on 
its journey through the network. 


L2 Signaling 
The mapping of RSVP objects to Layer 2 (per the ISO OSI Model) signaling, such as 
Frame Relay Network Devices (FRNDs) or ATM interfaces. 


Subnet Bandwidth Manager (SBM) 
Manages shared-media network bandwidth. In Windows 2000 Quality of Service, 
SBM functionality is incorporated into Admission Control Service (ACS). 


Resource Reservation Protocol (RSVP) 
Carries and disseminates QOS information to QOS-aware network devices along the 
path between a sender and one or more receivers for a given flow, and also to 
senders and receivers. 


802.1p 


Responsibility for QOS provisions on the local segment, and avoidance of the “all 
packets are treated equally” issue, falls onto the hub or switch servicing the segment. At 
such a level, the issue of differentiating between network packets, and perhaps treating 
them differently, must fall into the realm of the media access control (MAC) header. The 
MAC header (the lower half of Layer 2 in the ISO OSI Model) is the only part of a packet 
that hubs or switches investigate in their scope of work. 


802.1p provides prioritization of packets traversing a subnet by the setting of a 3-bit 
value in the MAC header. Thus, when the local segment becomes congested and the 
hub/switch workload results in the delay (or dropping) of packets, those packets with 
flags that correspond to higher priorities will receive preferential treatment, and will be 
serviced before packets with lower priorities. | 
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Note that implementing 802.1p for QOS requires an 802.1p-aware network interface 
card, an 802.1p-aware device driver, and an 802.1p-aware switch. 


Differentiated Services | 


Differentiated services enables packets that pass through network devices operating on — 
Layer 3 information, such as routers, to have their relative priority differentiated from one 
another. Differentiated services uses 6 bits in the IP header to specify its value, called 
the DSCP (DiffServ code point); the first 6 bits of the TOS field, the first three of which 
were formerly used for IP precedence. Differentiated services has subsumed IP 
precedence, but maintains backward compatibility. 


With differentiated services marking, Layer 3 devices can establish aggregated 
precedence-based queues and provide better service (when packet service is subject to 
queuing, as is the case under significant traffic loads) to packets that have higher 
relative priority. For differentiated services to be effective, Layer 3 devices must be 
DSCP-enabled. 


L2 Signaling 

WAN technology manipulates Layer 1, Layer 2, and to a certain extent Layer 3 
information, as it transmits data over the telecommunications network. Since quality of 
service is an end-to-end solution that provides quality of service for data transferred 
across the network, there must be a means by which data passing through WAN 
interfaces can be associated with some sort of preferential or nonpreferential treatment. 
Such a requirement necessitates the mapping of ROVE or other QOS parameters to 
WAN technology QOS interfaces. 


Layer 2, however, is where QOS technology interacts most with the WAN’s underlying 
signaling, since it is in Layer 2 where existing WAN technologies implement their own 
native QOS components. L2 signaling, in Windows 2000 QOS terms, takes QOS 
information such as parameters that are carried in RSVP messages to or through each 
network node between end devices, and maps that QOS information to native WAN 
technology QOS interfaces. For example, the classical IP over ATM (CLIP) module in 
Windows 2000 specifically maps Windows 2000 QOS settings to an appropriate ATM 
class of service. 


Subnet Bandwidth Manager 

The Subnet Bandwidth Manager (SBM) is the QOS component that provides resource 
management and policy based—admission control for QOS-aware applications using 
shared media subnets (Ethernet, for example). The SBM is based on an IETF draft that 
defines SBM functionality and its general implementation. 


SBM is implemented in Windows 2000® through the Admission Control Service (ACS). 
ACS is a Windows 2000 service that resides on a Windows 2000 Server. 
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Policy-Driven QOS Components 


Admission Control Service (ACS) 
A Windows 2000 service, residing on a Windows 2000 Server, that inserts itself into 
the RSVP message path to enforce Windows 2000 Directory Service based—network 
admission control policies for QOS—enabled clients. 


~ Local Policy Module (LPM) 


A Microsoft-provided module that provides network resource—access Hecisions: based 
on policies configured in Active Directory services, for the Subnet Bandwidth Manager 
(SBM) component. The LPM makes policy decisions based on policy information 
contained in RSVP-based signaling messages sent by clients. | 


Policy Information 
Identity-based policy information sontained in RSVP messages is submitted to the 
LPM, on which LPMs base policy decisions. Policy information is generated by a 
Microsoft-provided DLL that resides on Windows clients providing turnkey 
implementation of Windows 2000 QOS. Policy information is securely transmitted 
across the network in a session that is secured by a Kerberos ticket. Microsoft- 
provided policy information is data generated by the Microsoft-provided DLL, and not 
QOS service components (rather, they are data that is generated by a 
QOS component). 


RSVP 
Carries policy data between end nodes and the ACS/SBM. RSVP also carries 
rejections to admission requests back to the requesting node. 


Local Policy Module API (LPM API) 
The programmatic interface for LPMs to interface with the SBM in ACS. 


For a figure that shows where these components fit into the end-to-end QOS enabled— 
network picture, see QOS Documentation Structure. 


Admission Control Service 


Admission control service (ACS), is a Windows 2000 QOS component that regulates 
subnet usage for QOS-enabled applications. The ACS exerts its authority over 

QOS aware applications or clients by placing itself within the RSVP message path. With 
this placement, ACS effectively intercepts RSVP PATH, RESV, PATH_ERR, | 
RESV_ERR, PATH_TEAR, and RESV_TEAR messages and passes the messages’ 
policy information to Local Policy Modules (LPMs) for authentication. This exertion of 
ACS authority occurs on each interface (or shared medium) over which a given QOS 
flow must traverse. For a simplified example, if ACS is functioning on a source subnet 
and a (different) destination subnet for a owen flow, policy restrictions are enforced by 
the ACS on each subnet. 


ACS regulation is based on available network resources and on administratively- 
configurable information on users, or group policy. ACS is implemented as a 
Windows 2000 service on a Windows 2000 Server. 
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Local policy modules (LPMs) fall within the fold of ACS functionality, and can be 
considered an integral part of the ACS. With the default LPM, Microsoft Identity LPM 
(MSIDLPM) user information in the intercepted RSVP message is used to look up user 
policy in Windows 2000 Active Directory services. MSIDLPM then makes policy 
decisions based on information found in Active Directory services. 


Another ACS component, the Policy Control Module (PCM), actually mediates the 
interaction between the ACS and LPMs. If there are multiple residential LPMs, the PCM 
will send all policy data objects contained in the received RSVP messages to each LPM, 

gather all responses, perform logical checks on the information, aggregate it, and return 
_ the combined response to the ACS. 


If network resources are available and if the policy check succeeds, the RSVP message 
and its policy information is sent to the next hop (or the previous hop, if it is a PATH or 
RESV message). In this way, ACS acts as the logical gatekeeper for RSVP message 
propagation across the network by rejecting requests under the following conditions: — 


e If local segment resources aren’t available to provide the requested level of QOS 
(the SBM functionality of the ACS). 


e lf the sender or receiver doesn’t have appropriate policy permission to transmit data 
with the requested parameters. 


When such conditions occur, no network nodes beyond the ACS (in the appropriate 
direction) receive any of the RSVP messages rejected by the ACS. However, the error 
_ messages due to the rejection will traverse the network to get to the Hetwork mode that 
made the request. | 


This provides twofold service. It keeps unnecessary RSVP signaling traffic from 
traversing the network by keeping lame-duck RSVP messages from running across the 
network, and it preserves processing resources for routers and WAN Interface Cards 
(WANICs) since they will not have to handle such RSVP messages. Note that any node 
that declines requests based on policy failure, however, will return an RSVP error 
message to the sender, indicating failure. Clients will not transmit anything if if their 
request is rejected by ACS. 7 : 


Though ACS is a Windows 2000 Qos component, its services include other QOS 
components, such as the Subnet Bandwidth Manager (SBM) and its LPM interface. 


Policy Information 


Microsoft provides identity policy information through a DLL installed on Q0s- enabled 
Windows clients such as Windows 2000 Server and Windows 2000 Professional. 


The policy information is incorporated in RSVP resource reservation requests, which in 
turn get sent out onto the network in the form of RSVP messages. This policy 

information is intercepted by the Admission Control Service (ACS), which includes SBM 
functionality as part of its fundamental service suite. The ACS services such requests by © 
checking whether the requesting client has authorization to use network resources on 
the local subnet. If successful, the policy information is forwarded to the next network 
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node for subsequent policy checking, and such activity continues toward the intended 
receiver, along the data path of network nodes, until the request is rejected or the 
intended receiver (the node with which the sending client wishes to communicate) is 
reached. | 


Local Policy Module 


The Local Policy Module (LPM) is a QOS component responsible for retrieving and 
returning policy-based decisions used by the Admission Control Service (ACS). A default 
LPM provides an interface to policy information that is configured and stored in 

Windows 2000 Active Directory services. LPM is a generic term used to supply policy- 
based admission control decisions for ACS. An LPM makes these decisions using 
policies that are generally configured by network administrators, and stored in policy 
databases. An LPM is usually implemented as a DLL. 


LPMs are used on the ACS server. Client QOS components that generate the policy 
element reside on the client, and are capable of creating policy information that is carried 
in RSVP messages to the ACS (which then gets forwarded down to the LPM). It is 
possible to install an LPM on the ACS server for which there is no corresponding 
component on the client; for example, an ACS-based LPM could enforce “time-of-day” 
policies, or could be capable of communicating with a COPS server. 


It is important to note the difference between IETF-draft technologies and the Microsoft 
implementation of them. Subnet Bandwidth Manager (SBM), for example, is a 
technology derived from an IETF-draft proposal for regulating access to 802 subnets 
(draft-ietf-issll-is802-sbm-08.txt). ACS is a Windows 2000 service (and a QOS 
component) that incorporates SBM technology within its fold to incorporate regulation of 
access to 802 subnets in accordance with policy control. 


LPM API 


The local policy module application programming interface (LPM API) is the 
programmatic interface by which LPMs communicate and interact with the Admission 
Control Service (ACS). The LPM API also specifies how LPMs are registered and 
initialized within the constructs of the ACS. 


Such interaction is actually regulated by an abstraction module called the Policy Control 
Module (PCM). Because it is possible to have multiple LPMs, the PCM manages the 
policy-based decision information that LPM modules return. Note that LPMs may 
selectively accept or reject flows. For example, an LPM can receive an RSVP-based 
request from the PCM that has multiple flow requests; the LPM can then selectively 
accept or reject individual flows within that request, and return the results to the PCM. 
Note, too, that the PCM can manage information returned from multiple LPMs (if multiple 
LPMs are installed on the system), perform logical aggregation of their results, and then 
return aggregated information to the ACS. 
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The LPM API consists of a handful of functions used to allow its interaction with the 
ACS. The interaction of an LPM with its corresponding policy store or server is excluded 
from this interface; such interfacing would be proprietary to the LPM and the policy Store 
or server. 


LPM Byte Reordering 


The RSVP protocol submits policy information in network-byte order, as illustrated in the 
following example: 


As you can see from the example, in network-byte ordering, the bits in any given byte 
are ordered such that the first bit (base zero) is bit zero, and the following bits are 
ordered sequentially through the last bit (bit position seven, base zero). 


The Microsoft LPM, Msidlpm.dll, reorders these bits in order to put them into host-byte 

— order. This is an important distinction because bit-based flags can be used to designate 
certain values in the PCM-LPM interaction. The following example illustrates host-byte - 
ordering: 


As you can see from the example, host byte ordering begins with the last bit in the byte 
_ (bit position seven, base zero) and progressing sequentially through the byte to bit 
position zero. | 


| Installing an LPM 


For additional LPMs to function on a system, you must install the LPM on the 
Windows 2000 Server computer on which it will function. Note that the Microsoft- 
provided LPM, Msidlpm.dll, is installed by default with Windows 2000 Quality of Service. 


- To install an LPM ona system 


1. Create a registry entry. The key in which the entry must be created is 
~ HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\RSVP\PCM Config\ 
— ActiveLPMs 


a. The entry type is REG_MULTI_SZ 
b. The value of the entry is the name of the LPM DLL 
2. Then, place the DLL into the Windows 2000 System32 directory. 


RSVP and QOS 


Resource Reservation Protocol (RSVP) plays a multifaceted role in the provisioning and 
signaling of QOS reservation requirements in Windows 2000. The following pages 
outline how RSVP carries out that role. 
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RSVP 


Resource Reservation Protocol (RSVP) is an IETF-draft networking protocol dedicated 
to being the facilitator and carrier of standardized QOS information and parameters. 
RSVP carries generic (industry-defined) QOS parameters from end nodes (inclusive) to 
each QOS-aware network device included in the path between RSVP session members. 
That is, RSVP is a means by which end nodes and network devices can communicate 
and negotiate QOS parameters and network usage admission. 


RSVP is a multifaceted protocol—it is central to application-driven, network-driven, and 
policy-driven QOS activities—it is the carrier on which Windows 2000 systems send 
QOS parameters and information to the network. RSVP has its own objects that can be 
filled or interrogated to specify or determine the requested QOS parameters that are 
either requested by the application, required of the network device, or applied for by 


the user. 


Since RSVP has its own clearly-defined objects, the implementation of RSVP within 
Windows 2000 requires QOS parameters to be mapped into (or on the receiving end of 
RSVP messages, derived from) RSVP objects. 


From an application-driven perspective, RSVP is the means by which an application’s 
requests are transported through the network (a container, though one with specifically 
defined compartments). Calls to the QOS API provide information to the RSVP SP, 
which then maps such information into predefined RSVP objects for transmission across 
the network. : 


RSVP provides a mechanism for end systems to convey information to network devices 
about application data flow. Network devices can then take QOS- or policy-related action 
based on this information. 


From a policy-driven perspective, RSVP provides the necessary user information within | 
industry standard—RSVP objects (much like a set of containers, each of which is defined 
based on its standard formats), that facilitate the exchange of user identity and 
admission requests. 


Although RSVP can be considered responsible for the bulk of Windows 2000 QOS 
interaction among end nodes, it is possible to achieve QOS without RSVP signaling, 
such as by using traffic control facilities available with Windows 2000 QOS. 
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QOS Programming 


Basic QOS Operations 


The RSVP Service Provider (RSVP SP) is where developers can enable their 
applications to take advantage of the QOS capabilities built into Windows 2000. The 
RSVP SP provides a service layer; by sitting between applications that want to take 
advantage of Windows QOS capabilities and QOS components. The RSVP SP shields 
developers from complexities involved in directly interfacing with QOS components such 
as RSVP, traffic control, and local policy modules. , 


The process of QOS-enabling an application includes enabling the application to perform 
the following: 


e Receiving QOS-enabled Data 
e Sending QOS-enabled Data 
e Closing the QOS connection 


Throughout the course of a QOS session, applications also need to be able to manage 
the QOS connection. 


Note that there are other components that may affect the success of QOS-enabled 

connection requests—such as policies in routers or on switches. For the purpose of 
explaining the process of QOS-enabling applications, the effect of these other QOS 
components will be addressed apart from the process of QOS enabling an application 
with the RSVP SP. 


QOS- Enabling Your Application 


QOS is enabled through the use of specific Windows Sockets APIs, as well as APIs and 
structures created specifically for use with QOS. Applications taking advantage of 
Windows QOS use Windows Sockets 2 APIs, in conjunction with QOS APIs and 
structures, to create a connection and provide QOS parameters that articulate the — 
application’s QOS requirements. QOS APIs and structures are also used to maintain 

(or change) settings associated with a particular QOS session. 


The call sequence involved in establishing and maintaining a Qos- enabled connection 
generally includes preparation calls, such as enumerating protocols then querying 
available protocols for QOS capability. The process of enumerating and querying 
Bee for GOs capability is is outlined in | Opening a Q08-Enabled Socket. 
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Opening a QOS-Enabled Socket 


The services and service quality guarantees provided by the RSVP SP require a QOS- 
enabled socket. The process of finding a QOS-enabled protocol involves the following 
steps: 


1. Call the WSAEnumProtocols function to enumerate the existing protocols. 


2. Loop through the enumerated protocols to find a protocol that supports QOS. QOS 
support is indicated by the presence of the XP1_QOS_SUPPORTED flag in 
dwServiceFlags1 in the WSAPROTOCOL_INFO structure. 


3. Call the WSASocket function, and pass a pointer to the WSAPROTOCOL_INFO 
structure corresponding to the QOS-enabled protocol. Note that the RSVP SP 
requires an overlapped socket. Create the socket in overlapped mode by setting the 
WSA_FLAG_OVERLAPPED flag in the dwFlags parameter of the WSASocket 
function. 


Note Do not attempt to use the WSADuplicateSocket function to create QOS-enabled 
sockets; the WSADuplicateSocket function cannot be used on a QOS-enabled socket. 
Attempting to do so will result in the return of a WSAEINVAL error. 


Invoking the RSVP SP 


QOS-enabled connections are unidirectional. To enable a connection with service 
guarantees for both sending and receiving from a host, two individual QOS-enabled 
flows are required. Whether the QOS-enabled flow is for sending or receiving, the initial 
process of invoking the RSVP SP usually includes the use of one o the following 
Windows Sockets 2 APIs: 


e WSAConnect 

e WSAJoinLeaf 

e WSAAccept 

e WSAloctl(SIO_SET_QOS) 


Each of these functions invokes the RSVP SP on the application’s behalf, and begins 
the process of establishing Quality of Service between the receiver and sender. Each of 
these functions includes a parameter that provides the application with the capability of 
providing QOS-specific parameters. These QOS-specific parameters are provided 
through the QOS structure, which is included as a parameter of each of the three 
preceding functions (WSAAccept generally implements the QOS structure through the 
callback function provided in its JofnCondition parameter). 


Whenever an application calls the WSAConnect function, the WSAJoinLeaf function, or 
the WSAAccept callback function with a non-NULL pointer to the QOS structure, QOS 
functionality is implicitly invoked. This invocation includes enlistment of any other QOS 
components’ services (such as traffic control or RSVP signaling) by the RSVP SP on 
behalf of the application. 
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QOS technology and parameters are unidirectional, enabling different transmission 
parameters for sender and receiver. Additionally, RSVP semantics are receiver-centric, 
in that resources aren’t reserved until the receiver sends out a RESV message. Due to 
this unidirectional approach, differences exist in the behavior of the receiver and the 
sender. These differences are outlined in the Receiving QOS-Enabled Data and Sending 
QOS-Enabled Data sections. 


Providing the RSVP SP with QOS-specific Parameters 


In order for the RSVP SP to act on behalf of an application, the RSVP SP must be 
provided with QOS-specific parameters. These parameters come in the form of the 
following structures: 


e QOS 
e FLOWSPEC 


The QOS siructure is the all-encompassing structure for QOS-specific parameters, and 
is comprised of three parameters, two of which are FLOWSPEC structures (one for 
sending, one for receiving). 


The FLOWSPEC structure includes flow members, which are TokenRate, 
TokenBucketSize, PeakBandwidth, Latency, DelayVariation, ServiceType, 
MaxSduSize (maximum packet size permitted in the traffic flow), and 
MinimumPolicedSize. When the application provides values for these parameters, the 
RSVP SP can characterize the service quality being requested; this enables the RSVP 
SP to make appropriate requests to corresponding components of QOS. 


The third parameter of the QOS structure is the ProviderSpecific buffer, which is used for 
additional provider-specific QOS parameters that can not be specified in the 
FLOWSPEC structures. For more information about the ProviderSpecific buffer, see the 
section titled Using the ProviderSpecific Buffer. | 


QOS parameters for the FLOWSPEC structure may be common among certain _ 
application types. Such commonality lends itself to the establishment of standardized 
QOS parameters for a given type of transmission. The RSVP SP provides such 
standardization, and the ease of implementation that comes with prescribed service 
types, through the use of QOS templates, which are described i in detail in the QOS 
Templa les section. 


Further details of the QOS structure and the FLOWSPEC structure can be found in their 
respective API entries. 
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Receiving QOS-Enabled Data 


An application can begin receiving data from its QOS-enabled sender before the QOS- 
enabled reservation is established. The result of receiving data before the QOS 
reservation is established is that data is transmitted over the network without QOS — 
guarantees (as it would be in a non-QOS network). Once the QOS-enabled reservation 
is established, the receiver can receive data that conforms to the established QOS- 
parameters for the reservation. 


Inherent in the occurrence of events (such as the establishment of the QOS-enabled 
connection) is the need for an application to query for events. The RSVP SP provides | 
mechanisms that enable event notification. These mechanisms differ depending on 
whether the application is receiving or sending data. 


As a receiver on a QOS-enabled connection, a host may initiate some or all of the 
following actions: | 


e As implied in the section titled Providing the RSVP SP with QOS-specific oaraineien 
a receiver must provide QOS-specific parameters to the RSVP SP. These parameters 
are provided in the ReceivingFlowSpec parameter of the QOS structure, which is 
‘provided through the use of the WSAConnect function, the WSAJoinLeaf function, 
the WSAAccept callback function, or ee ie Windows Sockets 2 SIO_ SET_ QOS 
~ IOCTL opcode. 


e To streamline the establishment of existing, common settings for the aos structure, 
an application can use the WSAGetQosByName function to enumerate, and then 
retrieve an existing QOS template, and apply the values in that template (in the form 
of a QOS structure) to the QOS structure in the Windows Sockets function call. See 
the section titted QOS Templates for more information on QOS templates. 


e The application may then send data. Data sent per the constraints of the established 
QOS-specific parameters is considered conforming data. Data that falls outside those 
parameters, or nonconforming data, is handled differently based on the 
QOS_OBJECT_SD_MODE setting, which is particular to traffic control. Options for 
nonconforming data include relegating it to a best-effort transmission to od 
nonconforming packets. 


e The application may want to monitor RSVP SP events in order to monitor the QOS- 
enabled connection status. For example, the application uses the status information 
and error codes provided with FD_QOS events. Other RSVP SP events that an 
application may want to monitor include using an RSVP_RESERVE_INFO object to 
request arrival confirmation of a RESV message. 


e When the application receives notification of certain events, it may want to take 
appropriate action to modify its QOS settings or parameters. For example, if an 
application is notified of the arrival of a PATH message, it must use the Windows 

- Sockets 2 SIO_GET_QOS IOCTL opcode in order to retrieve pertinent QOS 
information, such as the sender’s Tspec and the path’s Adspec. Information provided 
in the PATH message may be used by the application to modify its initial 
QOS-specific parameters to match the sender’s Tspec. For more information on 
Tspec and Adspec, see the section titled RSVP SP and RSVP. 
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sending QOS-Enabled Data 


As a sender on a QOS-enabled connection, the events differ somewhat from the 
receiver's collection of available actions. Where senders initiate connections and request 
certain QOS-specific parameters, receivers respond to such requests (note that network 
devices between the receiver and sender a/so react to receiver requests, and may reject 
requests before they ever reach the sender). 


As a sender on a QOS-enabled connection, a host may initiate some or all of the 
following actions: 


e Sending hosts must inform the RSVP SP of QOS-specific parameters in order to 
enable the RSVP SP to interact with other QOS components on the sending host’s 
behalf. QOS-specific parameters are provided to the RSVP SP through the 
SendingFlowspec member of the QOS structure, which itself is a parameter of the 
WSAConnect function, the WSAAccept function’s ConditionFunc placeholder, and 
the WSAJoinLeaf function. The SendingFlowspec member can also be provided 
through the use of the SIO_SET_QOS IOCTL opcode. 


e The QOS-specific members (SendingFlowspec) are based on the application’s 
knowledge of the data transmission characteristics appropriate for the application. For 
example, bandwidth requirements for database queries of a mission-critical 
application may be different than bandwidth requirements for low-quality audio 
broadcasts. Latency boundaries may also be different for those types of applications 
(note that latency boundaries are only available with Guaranteed Service). Therefore, 
the application is best equipped to provide appropriate QOS-specific transmission 
parameters, perhaps through the use of a QOS template. | 

e Senders may use the WSAGetQosByName function to enumerate, and then retrieve 
preinstalled QOS templates that include QOS-specific parameters with appropriate 
transmission characteristics based on the type of application. For example, there may 
be a template called RADIOBCAST associated with a QOS structure that 

_ automatically applies the most appropriate QOS settings for radio broadcast senders. 
It is the application’s responsibility to ensure its traffic remains within the bounds of 
FLOWSPEC members obtained using the WSAGetQosByName function; traffic that 

exceeds those parameters will be treated as nonconforming, and may result in 
degradation of quality. 


-@ Senders may configure additional traffic control parameters by including beCR in the 
ProviderSpecific buffer, such as handling nonconforming packets through setting of 
~ the SD_MODE. 


e The sender may monitor RSVP SP events to maintain the QOS-enabled connection, 
such as the arrival of RESV messages. Often, the sender will want to monitor status 
information and error codes provided with FD_QOS events. For example, the sender 
may choose to stop transmission when the FD_QOS event 
WSA_QOS_NO_RECEIVER occurs, indicating that there are no QOS-enabled 
receivers for the transmission. 
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e The sending application may want to use the Windows Sockets 2 SIO_GET_QOS 
lIOCTL opcode to look up QOS-specific parameters associated with the arrival of a 
RESV message. 


e The sending application may want to use the Windows Sockets 2 SIO_CHK_QOS 
IOCTL opcode to query parameters that provide information about the QOS 
connection such as allowed sending rate, line rate, and others. 


Closing the QOS Connection 


There are a number of ways to close a QOS-enabled connection. Generally, any event 
that closes a socket also ends RSVP SP servicing on the socket. Examples of events 
that cause the RSVP SP to stop providing QOS functionality on a socket include: 


e Using the closesocket function to close the socket. 


e Using the shutdown function to disable sends or receives on a socket. Note, 
however, that shutting down only the receive capabilities leaves the QOS-enabled 
send capabilities for the socket intact, and that shutting down only the send 
capabilities of a socket leaves the QOS-enabled receive capabilities for the socket 
intact as well. 


e Using the WSAConnect function with the name parameter set to NULL. 


e Using the WSAloctl function with the SIO_SET_QOS IOCTL opcode, in which the 
ServiceType member corresponding to SendingFlowspec or ReceivingFlowspec 
(both of which are of FLOWSPEC) is set to SERVICETYPE_NOTRAFFIC or 
SERVICETYPE_BESTEFFORT. 


Note that setting SERVICETYPE_NOTRAFFIC or SERVICETYPE_BESTEFFORT 
selectively can disable RSVP SP service for sending and receiving individually. For 
example, setting the ServiceType member of SendingFlowspec to 
SERVICETYPE_NOTRAFFIC or SERVICETYPE_BESTEFFORT only terminates 
QOS servicing for sending, and setting the Service Type member of 
ReceivingFlowspec to SERVICETYPE_NOTRAFFIC or 
SERVICETYPE_BESTEFFORT only terminates QOS servicing for receiving. 


QOS Templates 


The use of QOS templates enables applications to leverage well-known QOS settings for 
common transmission types. Templates can reduce the complexity associated with 
setting QOS parameters, because they enable application programmers to choose from 
established QOS settings (by using included and existing templates), or enable 
application programmers to create additional templates based for special QOS needs of 
applications, then simply apply that template to subsequent connections. 
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The RSVP SP provides three functions that facilitate the enumeration, use, creation, and 
deletion of QOS templates. These functions are: 

e WSAGetQOSByName 

e WSCinstallQOSTemplate 

e WSCRemoveQOSTemplate 


There are four activities associated with using QOS templates: 


e Enumerating Available QOS Templates 
e Applying a QOS Template 

e Installing a QOS Template 

e Removing a QOS Template 


Enumerating Available QOS Templates 


_In order to discover which templates are available on a given system, an application can 
enumerate the available QOS templates, using the WSAGetQOSByName function. 


The process of using the WSAGetQosByName function to enumerate available QOS 
templates follows a set of steps, as outlined in the following list: 


1. The application calls the WSAGetQOSByName function with the /oOQOS parameter 
set to NULL, and a pointer to a structure of type WSABUF provided for the 
lpQOSName parameter. 


2. A list of available QOS template names is returned in the WSABUF structure pointed 
to by IpPQOSName. 


3. The application peruses the available templates, and selects an aSpioenale template, 
based on the template’s name (codec), to service the application’s required QOS 
parameters. 


Once the list of available QOS templates is obtained, the application may apply a QOS 
template to a requested connection. The process of applying a QOS template is 
explained in the section called Applying a QOS Template. 


Applying a QOS Template — 

When an application knows the name of the QOS template it wants to use, the process 
of applying the QOS template is implemented through the WSAGetQOSByName 
function. The following steps outline the process necessary to apply a QOS template: 


1. The application then implements a QOS template by making a call to the 
WSAGetQOSByName function. In the function call, the application passes the 
template name in the /oDQOSName parameter, and provides a pointer to a QOS 
structure to be filled with the template’s settings in the Pact parameter with a NULL 
string. 


2. The RSVP SP fills the QOS structure pointed to in /pPQOS with the parameters from 
the selected QOS template. 
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3. The application then sets members of its SendingFlowspec and 
ReceivingFlowspec members of the QOS structure with values that correspond to 
the values of the associated template. (SendingFlowspec and ReceivingFlowspec 
are members of the QOS structure, and both are of type FLOWSPEC.) When using a 
QOS template, you should ensure that your application conforms to the transmission 
characteristics specified by the template being used. 


4. The application may then make a QOS-enabled connection request, and by using the 
QOS structure filled in Step 2, implement the QOS template’s QOS parameters as 
part of the request. 


For applications that do not know the name of the QOS template they want to use, or 
want to enumerate the available QOS templates, the process outlined in Enumerating 
Available QOS Templates should be followed. 


Installing a QOS Template 


Under certain circumstances, such as when available QOS templates do not fit required 
or desired QOS parameters, an application may want to install a QOS template of its 
own. By installing a QOS template that is tailored specifically to its needs, the application 
can benefit from easier and more consistent implementation of QOS parameter 
requests. 


Note that the installation of a QOS template requires administrative privilege. The 
process of installing a QOS template is contained within the WSCinstallQ@OSTemplate 
function. Essentially, a successful call to the WSCInstallQ@OSTemplate function installs 
a QOS template and associates the template with the name provided in the /pDQOSName 
parameter. Once the QOS template is installed with the WSCInstallQOSTemplate 
function, it can be applied to a connection through the use of the WSAGetQOSByName 
function. 


Removing a QOS Template 

The process of removing a QOS template is contained within the 
WSCRemoveQOSTemplate function. Note that the removal of a QOS ieinplaien requires 
administrative privilege. For more details about the removal of a QOS template, see the 
WSCRemoveQOSTemplate reference page. 


Built-in QOS Templates 


~The RSVP SP provides a set of built-in QOS templates that enable applications to apply | 


well-known codecs to QOS connection requests. The QOS templates provided are as 
follows: 


° G711 

° G723.1 

e G729 
H263QCIF 
e H263CIF 
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e H261QCIF 
e H261ClIF 
¢ GSM6.10 


RSVP SP Error Codes 


The RSVP SP provides a rich set of error codes and error values that enable 
applications and service providers to get detailed feedback when errors in processing 
occur. | 


RSVP SP errors (and all QOS errors) are retrieved using the SIO_GET_QOS IOCTL 

Call. SIO_GET_QOS returns a QOSstructure, and the error codes are returned in a 
RSVP_STATUS_INFO object provided in the ProviderSpecific buffer in the QOS _ 
structure. 


The reference pages in this section enable application and service developers to 
become familiar with the RSVP SP error code/error value family, and provide suggested 
actions when such errors arise. 


Error Codes 


The following table provides error codes, a description of the error code, and if 
applicable, the action that the application should take in the event the error is 


encountered. 
Error code Description Application response 
GQOS_NO_ERRORCODE No error occurred, 
| or the error code 
is unavailable. 
GQOS_RSVP The error occurred Check the QOS call 
7 inthe local RSVP — sequence. 
engine. 
GQOS_KERNEL_TC The error occurred Depending on the specific 
: in local traffic error value, the application 
control. may retry the operation 


with reduced QOS 
| requirements. 
GQOS_NET_ADMISSION Admission failure, | Stop the operation, retry 
| due to the SBM with reduced QOS 
(part of the ACS). requirements, or try later. 
GQOS_NET_POLICY | A policy-related Stop or retry with reduced - 
| a | error occurred. QOS requirements 
(depending on the specific 
error value). 


(continued) 
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(continued) 


Error code 


Description 


GQOS_ERRORCODE_UNKNOWN 


GQOS_API 
GQOS_RSVP_SYS 
GQOS_KERNEL_TC 


Error Values 


Application response 


The following table provides error values, a description of the error value, and if 
applicable, the action that the application should take in the event the error is 


encountered. 


Error value 


GQOS_NO_ERRORVALUE 


GQOS_ERRORVALUE_UNKNOWN 


Admission (resource) Error Values 
GQOS_OTHER 
GQOS_DELAYBND 


GQOS_BANDWIDTH 
GQOS_MTU 
GQOS_FLOW_RATE 


~GQOS_PEAK_RATE 


Description 


No error occurred, or the 


error value is unavailable. 


An upstream QOS- 
enabled device cannot 
meet the specified delay- 
bound requirement. 


An upstream QOS- 
enabled device cannot 
meet bandwidth 
requirement. 


The Maximum 
Transmission Unit (MTU) 
in FLOWSPEC is too 
large. 


An upstream QOS- 
enabled device cannot 
meet bandwidth 
requirement. 


An upstream QOS- 
enabled device cannot 
meet bandwidth - 
requirement. 


Application response 


Retry the operation with a 
more relaxed delay-bound 
requirement. 


Retry the operation with a 
more relaxed bandwidth 
requirement. 


Adjust the packet size and 
retry the operation. 


Retry the operation with a 
more relaxed bandwidth 
requirement. 


Retry the operation with a 
more relaxed bandwidth 
requirement. 


Error value 


Policy Errors 


GQOS_POLICY_ERROR_UNKNOWN 


GQOS_POLICY_GLOBAL_ 
DEF_FLOW_COUNT | 


GQOS_POLICY_GLOBAL_ 
GRP_FLOW_COUNT 


GQOS_POLICY_GLOBAL_ 
USER_FLOW_COUNT 


GQOS_POLICY_GLOBAL_ 
UNK_USER_FLOW_COUNT 


GQOS_POLICY_SUBNET_ 
DEF_FLOW_COUNT 


GQOS_POLICY_SUBNET_ 
GRP_FLOW_COUNT 


GQOS_POLICY_SUBNET_ 
USER_FLOW_COUNT 


GQOS_POLICY_SUBNET_ 
UNK_USER_FLOW_COUNT 


GQOS_POLICY_GLOBAL_ 
DEF_FLOW_DURATION 


GQOS POLICY GLOBAL_ 
GRP_FLOW_DURATION 


GQOS_POLICY_GLOBAL_ 
USER_FLOW_DURATION 
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Description 


A policy error occurred for 
an unknown reason. 


Policy error: the operation 
would exceed the global 
default-policy flow count. 


Policy error: the operation 
would exceed the global 
group-policy flow count. 


Policy error: the operation 
would exceed the global 
user-policy flow count. 


Policy error: the operation 
would exceed the 
unknown user-policy flow 
count. 


Policy error: the operation 
would exceed the subnet 
default-policy flow count. 


Policy error: the operation 
would exceed the subnet 
default-policy flow count. 
Policy error: the operation 
would exceed the subnet 
default-policy flow count. 
Policy error: the operation 
would exceed the subnet 
default-policy flow count. 


Policy error: the operation 


- would exceed the global 


default-policy flow 
duration. 


Policy error: the operation 
would exceed the global 
group-policy flow | 
duration. | | 
Policy error: the operation 
would exceed the global 
user-policy flow duration. 


Application response 


Abort or retry ata 
later time. 


Abort or retry at a 
later time. | 


Abort or retry ata 
later time. 


Abort or retry ata 
later time. 


Abort or retry ata 
later time. 


Abort or retry at a 
later time. 


Abort or retry ata 
later time. 


Abort or retry ata 
later time. 


Abort. 


Abort. 


Abort. 


(continued) 
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(continued) 
Error value 


Policy Errors 


GQOS_POLICY_GLOBAL_ 
UNK_USER_FLOW_DURATION 


GQOS_POLICY_SUBNET_ 
DEF_FLOW_DURATION 


GQOS_POLICY_SUBNET_ 
GRP_FLOW_DURATION 


GQOS_POLICY_SUBNET_ 
USER_FLOW_DURATION 


GQOS_POLICY_SUBNET_ 
UNK_USER_FLOW_DURATION 


GQOS_POLICY_GLOBAL_ 
DEF_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 
GRP_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 
USER_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 
UNK_USER_FLOW_RATE 
GQOS_POLICY_SUBNET_ 
DEF _FLOW_RATE 


GQOS_POLICY_SUBNET_ 
GRP_FLOW_RATE 


GQOS_POLICY_SUBNET_ 
USER_FLOW_RATE 


Description 


Policy error: the operation 
would exceed the 


unknown user-policy flow — 


duration. 


Policy error: the operation 
would exceed the subnet 
default-policy flow 
duration. 


Policy error: the operation 
would exceed the subnet 
group-policy flow 
duration. 

Policy error: the operation 
would exceed the subnet 
user-policy flow duration. 


Policy error: the operation 
would exceed the subnet 
unknown user-policy flow 
duration. 


Policy error: the operation 
would exceed the global 
default-policy flow rate. 


Policy error: the operation 
would exceed the global 
group-policy flow rate. 


Policy error: the operation 
would exceed the global 
user-policy flow rate. 


Policy error: the operation 
would exceed the 
unknown user-policy 

flow rate. 

Policy error: the operation 
would exceed the subnet 
default-policy flow rate. 


Policy error: the operation 


~ would exceed the subnet 


group-policy flow rate. 
Policy error: the operation 
would exceed the subnet 
user-policy flow rate. 


Application response 


Abort. 


Abort. 


Abort. 


Abort. 


Abort. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 
Abort or retry with reduced 


QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Error value 


Policy Errors 


GQOS_POLICY_SUBNET_ 
UNK_USER_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 


DEF_PEAK_RATE 


GQOS_POLICY_GLOBAL_ 


GRP_PEAK_RATE 


GQOS POLICY GLOBAL. 


USER_PEAK_RATE 


GQOS_POLICY_GLOBAL_ 


UNK_USER_PEAK_RATE 


GQOS_POLICY_SUBNET_ 


DEF_PEAK_RATE 


GQOS_POLICY_SUBNET_ 


GRP_PEAK_RATE | 


GQOS_POLICY_SUBNET_ 


USER_PEAK_RATE 


GQOS_POLICY_SUBNET_ 
UNK_USER_PEAK_RATE 


GQOS_POLICY_GLOBAL_ | 


DEF_SUM_FLOW_RATE 


GQOS POLICY _GLOBAL_ 


| GRP_SUM_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 
USER_SUM_FLOW_RATE 
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Description 


Policy error: the operation 
would exceed the subnet 
unknown user-policy 

flow rate. 


Policy error: the operation 
would exceed the global 
default-policy peak rate. 


Policy error: the operation 
would exceed the global 
group-policy peak rate. 


Policy error: the operation 
would exceed the global 
user-policy peak rate. 


Policy error: the operation 
would exceed the 
unknown user-policy 
peak rate. 


Policy error: the operation 
would exceed the subnet 


- . default-policy peak rate. 


Policy error: the operation 
would exceed the subnet 
default-policy peak rate. 
Policy error: the operation 
would exceed the subnet 
default-policy peak rate. 


- Policy error: the operation 


would exceed the subnet 
default-policy peak rate. 
Policy error: the operation 
would exceed the global 
default-policy total 


~ flow rate. 


Policy error: the operation 
would exceed the global 
group-policy total 

flow rate. 

Policy error: the operation 


would exceed the global 


user-policy total flow rate. 
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Application response 


Abort or retry with reduced 
QOS requirements 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 


QOS requirements. 


Abort or retry with reduced 
QOS requirements. | 


Abort or retry with reduced | 


QOS requirements. 


Abort or retry with reduced 
QOS requirements. | 


Abort or retry with reduced 


QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


| Abort or retry with reduced 


QOS requirements. 


(continued) 
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(continued) 


Error value 


Policy Errors 


GQOS_POLICY_GLOBAL_ 
UNK_USER_SUM_FLOW_RATE 


GQOS_POLICY_SUBNET_ 
DEF_SUM_FLOW_RATE 


GQOS_POLICY_SUBNET_ 
GRP_SUM_FLOW_RATE 


GQOS_POLICY_SUBNET_ 
UNK_USER_SUM_FLOW_RATE 


GQOS_POLICY_SUBNET_ 
USER_SUM_FLOW_RATE 


GQOS_POLICY_GLOBAL_ 
DEF_SUM_PEAK_RATE 


GQOS_POLICY_GLOBAL_ 
GRP_SUM_PEAK_RATE 


GQOS_POLICY_GLOBAL. 
USER SUM PEAK RATE 


GQOS_POLICY_GLOBAL_ 
UNK_USER SUM PEAK _RATE 


GQOS_POLICY_SUBNET_ 
DEF_SUM_PEAK_RATE 


Description 


Policy error: the operation 
would exceed the | 
unknown user-policy total 
flow rate. 


Policy error: the operation 
would exceed the subnet 
default-policy total 

flow rate. 


Policy error: the operation 
would exceed the subnet 
group-policy total 

flow rate. 

Policy error: the operation 
would exceed the subnet 
unknown user-policy total 
flow rate. 


Policy error: the operation 
would exceed the subnet 
user-policy total flow rate. 


Policy error: the operation 
would exceed the global 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the global 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the global 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the global 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the subnet 
default-policy total 

peak rate. 


Application response 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Error value 


Policy Errors 


GQOS POLICY _SUBNET_ 
GRP SUM PEAK RATE 


GQOS_POLICY_SUBNET_ 
USER_SUM_PEAK_RATE 


GQOS_POLICY_SUBNET_ 
UNK_USER_SUM_PEAK_RATE 


GQOS_POLICY_UNKNOWN_USER 
GQOS_POLICY_NO_PRIVILEGES 


GQOS_POLICY_EXPIRED_ 
USER_TOKEN 


GQOS_POLICY_NO_RESOURCES 


GQOS_POLICY_PRE_EMPTED 


~GQOS_POLICY_USER_CHANGED 


GQOS_POLICY_NO_ACCEPTS 


GQOS_POLICY_NO_MEMORY 


GQOS_POLICY_CRAZY_FLOWSPEC 


GQOS_POLICY_ERROR_USERID 
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Description 


Policy error: the operation 
would exceed the subnet 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the subnet 
default-policy total 

peak rate. 


Policy error: the operation 
would exceed the subnet 
default-policy total 

peak rate. 


Policy error: the user is 
unknown. 


Policy error: the user has 
no privilege. 

Policy error: the user 
identification token has 
expired. | 
Policy error: LPM out of 
resources (memory). 


Policy error: the operation 
was pre-empted by a 
higher priority request. 
Policy error: user 
identification has 
changed after the 
reservation was 
approved. 

Policy error: the operation 
was rejected by all policy 
modules. 

Policy error: LPM out of 
memory. 

Policy error: invalid 
FLOWSPEC. 


Unable to understand the 


user ID 


Application response 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Abort or retry with reduced 
QOS requirements. 


Check the user’s 


identification and security 


attributes. 


Abort. Possible shut down 
on sender or receiver. 


Abort or retry. 


Abort or retry at a 
later time. 


Abort or retry at a 
later time. 


Abort. 


Abort. 


Abort or retry ata _ 
later time. 


Check the FLOWSPEC 
structu re. | | 


Abort. 
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(continued) 


Error value 


RSVP Errors 
GQOS_NO_PATH 
GQOS_NO_SENDER 
GQOS_BAD_STYLE 
GQOS_UNKNOWN_STYLE 
GQOS_BAD_DSTPORT 
GQOS_BAD_SNDPORT 
GQOS_AMBIG_FILTER 


GQOS_PREEMPTED 


GQOS_UNKN_OBJ_CLASS 
GQOS_UNKNOWN_CTYPE 
GQOS_INVALID 

API Errors 
GQOS_API_BADSEND 


GQOS_API_BADRECV 
GQOS_API_BADSPORT 


Traffic Control System Errors 


GQOS_TC_GENERIC 
GQOS_TC_INVALID 
GQOS_NO_MEMORY 


Description 


No matching path state 
for the reservation 
request. 

No sender information for 
the reservation request. 
Mismatch in Resv style. 


The Resv style is 
unknown. 

Conflicting or invalid 
destination port. 
Conflicting or invalid 
source port. 
Ambiguous filter 
specification in RESV. 
Service preempted due to 
a higher priority 
reservation. 

Invalid RSVP syntax in 
objects 

Invalid RSVP syntax in 
objects 

Invalid operation or 
parameters. 


Generic error. 


Not enough memory 
available to execute the - 
requested RSVP/traffic 
control operation. 


Application response 


Check the QOS call | 
sequence. 


Check the QOS call 
sequence. 

Check the RESV filter 
specifications. 

Check the RESV filter 
specifications. 

Check the QOS call 
sequence. 

Check the QOS call 
sequence. 

Check the RESV filter 
specifications. 

Try to invoke QOS again 
at a later time. 


Abort. 


Abort. 


Abort the operation or retry 
at a later time. 
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Error value Description 


Traffic Control System Errors 


GQOS_BAD_ADDRESSTYPE Traffic control error: 
invalid address type. 


GQOS_BAD_ DUPLICATE 
GQOS_CONFLICT 
GQOS_NOTREADY 


GQOS_WOULDBLOCK RSVPAtraffic control 
operation would block. 


GQOS_INCOMPATIBLE 
GQOS_BAD_SDMODE 


GQOS_BAD_QOSPRIORITY Traffic control error: 
invalid internal priority. 


GQOS_BAD_TRAFFICCLASS 


GQOS_NO_SYS RESOURCES Traffic control error: out of 
system resources. 


RSVP System Errors 
GQOS_OTHER_SYS 

~ GQOS_MEMORY_SYS 
GQOS_API_SYS 
~GQOS_SETQOS_NO_LOCAL_APPS 


Traffic Control Errors 


GQOS_CONFLICT_SERV Conflicting traffic control 
filters. 
GQOS_NO_SERV > The service is unknown 


| to local traffic control. 
GQOS_BAD_FLOWSPEC 

GQOS_BAD_TSPEC 

GQOS_BAD_ADSPEC 


WSAloctl Errors | 
GQOS_IOCTL_SYSTEMFAILURE 
GQOS_IOCTL_NOBYTESRETURNED 
GQOS_IOCTL_INVALIDSOCKET 


Application response 


Check the address type of 
the socket. 


Retry at a later time. 


Check the traffic control 
priority object. 


Abort or retry ata 
later time. 


Check the QOS 
specifications. | 
Check the Service Type 
parameter. 
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(continued) 


Error value Description 


SIO_SET_QOS Errors 
GQOS_SETQOS_BADINBUFFER 
GQOS_SETQOS_BADFLOWSPEC 
GQOS_SETQOS_COLLISION 


GQOS_SETQOS_ 
BADPROVSPECBUF 


GQOS_SETQOS_ILLEGALOP 
GQOS_SETQO$S_INVALIDADDRESS 
GQOS_SETQOS_OUTOFMEMORY 
GQOS_SETQOS_EXCEPTION 
GQOS_SETQOS_BADADDRLEN 
GQOS_SETQOS_NOSOCKNAME 
GQOS_SETQOS_IPTOSFAIL 


GQOS_SETQOS_ 
OPENSESSIONFAIL 


GQOS_SETQOS_SENDFAIL 
GQOS_SETQOS_RECVFAIL 


GQOS_SETQOS_ 
BADPOLICYOBJECT 


GQOS_SETQOS_ 
UNKNOWNFILTEROBJ 


GQOS_SETQOS_BADFILTERTYPE 
GQOS_SETQOS_BADFILTERCOUNT 
GQOS_SETQOS_BADOBJLENGTH 
GQOS_SETQOS_BADFLOWCOUNT 
GQOS_SETQOS_UNKNOWNPSOBJ 
GQOS_SETQOS_BADPOLICYOBJ 
GQOS_SETQOS_BADFLOWDESC 


GQOS_SETQOS_ 
~BADPROVSPECOBJ 


GQOS_SETQOS_NOLOOPBACK 
GQOS_SETQOS_ 
MODENOTSUPPORTED 
GQOS_SETQOS_ 
MISSINGFLOWDESC 


Application response 


Chapter 14 QOS Programming 


Error value Description Application response 


SIO_GET_QOS Errors 
GQOS_GETQOS_BADOUTBUFFER 
GQOS_GETQOS_SYSTEMFAILURE 
GQOS_GETQOS_EXCE:TION 
GQOS_GETQOS_INTERNALFAILURE 


SIO_CHK_QOS Errors 
GQOS_CHKQOS_BADINBUFFER 
GQOS_ CHKQOS_BADOUTBUFFER 
GQOS_ CHKQOS_SYSTEMFAILURE 
GQOS_CHKQOS_INTERNALFAILURE 
GQOS_ CHKQOS_BADPARAMETER 
GQOS_ CHKQOS_EXCEPTION 


Service Types 
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‘Service types enable an application to specify service quality requirements for a QOS- 
enabled connection. The availability of different service types enables the RSVP SP to 
categorize the QOS required by the application, and thereby decide the type of requests 


it (the RSVP SP) should make to complementary components on behalf of the 
requesting application. 


There are four primary service types included in the RSVP SP. 


Applications must choose which service type is most appropriate for their transmission 


requirements, based on traffic characteristics, performance requirements, user 


preferences, or any other criterion that influences how data should be transmitted. Also 


note that when an application invokes the RSVP SP to initiate QOS for a given 


connection, the ServiceType member of the FLOWSPEC structure (where the service 
type is specified) for both the SendingFlowspec and meconing’ loweper! members of 


the QOS structure must be specified. 


— Specifying either CONTROLLED LOAD or GUARANTEED for the SériiceT ype 
parameter implicitly invokes QOS service for the coliesPonong: direction of the 
QOS enabled connection. 


| In addition to the primary service types, the RSVP SP provides a csndaiy service types 


that enable application programmers and the RSVP SP to monitor or modify service 


provisions under certain circumstances, and on an ongoing basis. 


There are three secondary service types. 
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Primary Service Types 
The following four service types are considered primary service types: 


e BEST EFFORT 
e CONTROLLED LOAD 
e GUARANTEED 
e QUALITATIVE 


BEST EFFORT 


The BEST EFFORT service type instructs the RSVP SP to use the application’s QOS 
parameters as guidelines for service quality requests, and make reasonable effort to 
maintain the requested level of service. The BEST EFFORT service type does not make 
any guarantees that requested QOS parameters will be implemented or enforced, but 
can be used by senders to specify traffic control objects. 


CONTROLLED LOAD 


When the CONTROLLED LOAD service type is specified, the RSVP SP is instructed to 
provide end-to-end service quality that approximates the network behavior achieved 
from BEST EFFORT service under unloaded conditions. 


The result of specifying the CONTROLLED LOAD service type is that network devices 
and elements in the path between the QOS-enabled connection (the end-to-end path) 
can be expected to: | 


e Deliver a very high percentage of packets (packet loss approximates basic packet 
error rates for the transmission medium). 


e Transit delay by a very high percentage of transmitted packets will not greatly exceed 
the minimum transit delay experienced by any successfully delivered Packs at the 
speed of light. 


These defining characteristics of the CONTROLLED LOAD service type are based on 
definitions provided by RFC 2210. 


GUARANTEED 

When the GUARANTEED service type is specified, the RSVP SP and other QOS 

components included in the transmission of packets attempt to guarantee the level of 

service quality defined by the application’s provided QOS parameters. With the 

GUARANTEED service type, queuing algorithms isolate an application’s data flow (a 
flow is the unidirectional transmission of packets on a QOS-enabled ronnecton to 

provide the eee service characteristics. ie 
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e The application’s flow is isolated from other flows as much as possible. 


e The application’s flow is guaranteed the ability to transmit data at the TokenRate for 
the duration of the connection. 


e Ifthe application does not exceed TokenRate over time, latency is also guaranteed. 


The GUARANTEED service type is designed for applications that require precisely 
known service quality (QOS parameters), but would not benefit from better service. An 
example of such an application is a real-time control system application. The 
GUARANTEED service type is also designed to transmit within a specific delay bound. 


QUALITATIVE 


The QUALITATIVE service type is suited for applications that require better than BEST 
EFFORT service, but are unable to quantify their requirements. Applications that request 
QUALITATIVE service can supply an application ID policy object. Policy servers on the 
network use information in the application ID object to identify the application’s flow and 
assign it an appropriate quality of service. For more information on how to insert an 
application ID, see the Microsoft White Paper titled Inserting Application and Sub- 
application IDs or the IETF Internet Draft on APP ID, draft-ietf-rap-rsvp-appid-00.txt. 


Secondary Service Types 


The use of secondary service types enable an application programmer to modify QOS 

service guarantees in different ways, such as enabling QOS for only one direction of a 

bidirectional connection, disabling an existing QOS service guarantee, or disabling traffic 
control. Each of the following secondary service types are explained in this section: 


e SERVICETYPE_NOTRAFFIC. | 
e SERVICETYPE_GENERAL_INFORMATION 
e SERVICETYPE_NOCHANGE 


There are also two secondary service types that an application programmer can use in 
conjunction with the all primary service types, and the previously mentioned secondary 
service types. Application programmers can use the bitwise OR operator with these 

following two service type values to further refine the service type behavior they require: 


-@ SERVICE_NO_TRAFFIC_CONTROL 
e _ SERVICE _ NO_QOS_SIGNALING 


SERVICETYPE_ NOTRAFFIC 


Use of the SERVICETYPE_NO_ TRAFFIC service type indicates (or Specifies} that no 
QOS services are required in the associated direction. For example, if the 
SendingFlowspec specifies SERVICETYPE_NOTRAFFIC, then traffic sent on the 
specified connection would not receive QOS service provisions. In other words, Qos 
signaling for sent data would be disabled. 
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This service type is useful when QOS service guarantees are only required in one 
direction (and therefore not required in the opposite direction). The 
SERVICETYPE_NOTRAFFIC service type is also useful when QOS service provisions 
are no longer required in a specific direction, in which case the 
SERVICETYPE_NOTRAFFIC service type can be used in conjunction with the 
SERVICETYPE_NOCHANGE service type to disable QOS signaling in one direction, 
and leave the other direction’s QOS signaling unchanged. 


SERVICETYPE_GENERAL_INFORMATION 


The SERVICETYPE_GENERAL_INFORMATION service type is used in the 
SendingFlowspec parameter of a QOS structure to indicate that the sender can operate 
properly within any of the services. Note that 
SERVICETYPE_GENERAL_INFORMATION does not include any indication regarding 
the availability of the QUALITATIVE service type. 


SERVICETYPE_GENERAL_INFORMATION is only available to the sender; the RSVP 
SP returns an error if the receiver attempts to use the 
SERVICETYPE_GENERAL_INFORMATION service type. 


It is worth noting that BEST EFFORT is almost always available, since it makes no 
particular guarantee for service quality. The RSVP SP will do its best to meet service 
level requests for BEST EFFORT flows. Therefore, the 
SERVICETYPE_GENERAL_INFORMATION can more effectively be interpreted as 
advertising that either CONTROLLED LOAD or GUARANTEED service types can be 
selected by the receiver for the flow. 


Note, however, that routers in the path between end nodes may indicate that they do not 
support one or both of the (interesting) service types—CONTROLLED LOAD and 
GUARANTEED. 


SERVICETYPE_NOCHANGE 


The SERVICETYPE_NOCHANGE service type is useful when making changes to QOS 
parameters for one direction of a given flow. Specifically, the 
SERVICETYPE_NOCHANGE enables application developers to indicate or implement 
changes in one direction of a flow, without having to respecify unchanged QOS ~ 
parameters for the SERVICETYPE_NOCHANGE-specified direction of the flow. 


SERVICE _NO_TRAFFIC_CONTROL 


The SERVICE_NO_TRAFFIC_CONTROL service type instructs the RSVP SP not to 
invoke kernel traffic control. This secondary service type can be invoked using the 
bitwise OR operator with the following primary and secondary service types to further. 
specify an application’s quality of service requirements: 

e BEST EFFORT 

e CONTROLLED LOAD 

e GUARANTEED 
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QUALITATIVE , 

e SERVICETYPE_NOTRAFFIC | 
e SERVICETYPE_GENERAL_INFORMATION 
e SERVICETYPE_NOCHANGE 


SERVICE _NO_QOS SIGNALING 


The SERVICE_NO_QOS_SIGNALING service type may be set by the sending or 
receiving application. When this service type is specified, the RSVP SP does not invoke 
RSVP signaling, enabling the application to suppress the RSVP SP S invocation of 
RESV messages on the application’s behalf. 


This secondary service type can be invoked using the bitwise OR operator with the 
following primary and secondary service types to further specify an application’s quality 
of service requirements: 

e BEST EFFORT 

e CONTROLLED LOAD 

e GUARANTEED 

e¢ QUALITATIVE 

e SERVICETYPE_NOTRAFFIC © 

e SERVICETYPE_GENERAL_INFORMATION 

e SERVICETYPE_NOCHANGE 


Using Service Types 


The following sections provide information on how to use service tee in your 
application, including the directional implications of each of the primary and secondary 
service types, as well as a usage example. | 


Directional Implications of Service Types 


The impact of specifying each of these service types differs depending on whether is it 
sent in the SendingFlowspec or ReceivingFlowspec. To best illustrate the impact of 
specifying any of these service types, the following table explains the implications of 
each, depending on whether the service type is specified in the SendingFlowspec or the 
7 ReceivingFlowspec. 


754 


Volume 1 Winsock and QOS 


Service Types 
BESTEFFORT 


NOTRAFFIC 


CONTROLLEDLOAD 


GUARANTEED 


QUALITATIVE 


GENERAL_ 
INFORMATION 


NO_CHANGE 


In SendingFlowspec 


Indicates that only best- 
effort service is supported 
for this traffic flow. 


Indicates that there will be 
no traffic in this direction. 


Indicates that only 
controlled load service is 
supported for this 

traffic flow. 


Indicates that only 
guaranteed service Is 
supported for this 
traffic flow. 

Indicates that only 
qualitative service is 
requested for this 
traffic flow. 


Indicates that all service 


types are supported or this 


traffic flow. 
Allows an application to 


modify QOS in the receiving 


direction, while leaving the 
sending unchanged, or to 
provide ProviderSpecific 


parameters without altering 
values previously specified 


in the flowspec. 


In ReceivingFlowspec 


Requests best-effort service 
(no RSVP signaling treatment). 


Indicates that there will be no 
traffic in this direction. 


Ask the network for a controlled 
load reservation. 


Ask the network for a 
guaranteed reservation. 


Indicates that qualitative 
service is being requested for 
the traffic flow. 


N/A 


Allows an application to modify 
QOS in the sending direction, 
while leaving the receiving 
direction unchanged, or to 
provide ProviderSpecific 
parameters without altering 
values previously specified in 
the flowspec. 


Note that a sending application can specify a ServiceType parameter in the 
SendingFlowspec set to CONTROLLED_LOAD or GUARANTEED if it wants to limit the 
service type options presented to the receiver to just one service type. If the 
SendingFlowspec contains a service type of GENERAL_INFORMATION then both 
service types will be advertised as available from the sender (although intervening 
routers may indicate that they do not support one or both service types). 


Examples of Setting the Service Type 


The first example is a sending application that requires GUARANTEED service type, but 
does not want kernel traffic control. In this case, the application should set the 
Service Type in its SendingFlowspec to the following: 


SERVICETYPE_GUARANTEED | SERVICE_NO_TRAFFIC_CONTROL 


Chapter 14 QOS Programming 755 


Using the ProviderSpecific Buffer 


Most application developers will find that the RSVP SP and its functions provide all the 
necessary programmatic access to QOS parameters and settings. However, some 
applications may find it necessary to provide information or parameters that are not 
available through the FLOWSPEC structure. The ProviderSpecific buffer enables 
application developers to provide special QOS information, such as RSVP style, Resv 
confirmation request, or traffic control parameters and settings. 


The ProviderSpecific buffer is a member of the QOS structure, and is of type 
WSABUF. 


Structure of the ProviderSpecific Buffer 


The ProviderSpecific buffer includes a length field, anda pointer to a buffer. The buffer 
may include multiple objects, and each object must contain the following, in the order 
shown: 


e A type field that identifies the object. | 
e A length field that contains the length of the object, including the header. 
e The object data itself. 


Note that all objects referenced in the ProviderSpecific buffer must be contained within 
the same piece of contiguous buffer memory (the entire QOS structure is contained 
within a contiguous block of memory). 


Use of the ProviderSpecific Buffer as a Receiver 
Receivers can use the ProviderSpecific buffer to do the following: 


While making QOS requests, receivers can: 


e Specify nondefault RSVP reservation style, flow descriptors, and filter specifications. 
e Request RESERVE CONFIRMATION. 
e Specify one or more policy elements (policy information) to RSVP. 


While receiving notification, such as getting additional information from the sender, 
receivers can: 


e Retrieve policy information. 
e Retrieve QOS and RESV_ CONFIRM events. 


Use of the ProviderSpecific Buffer as a Sender 
Senders can use the ProviderSpecific buffer to do the following. 
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While making QOS requests, senders can: 


e Specify one or more policy elements (policy information) to RSVP. 
e Specify traffic control parameters such as shape/discard mode. 
e Specify policy information. 


While receiving notification, such as getting additional information from the sender, 
senders can: 


e Retrieve QOS events. 
e Retrieve policy information. 


Understanding Traffic Control 


Traffic control, commonly referred to as TC, regulates traffic on local hosts. Traffic 
control is responsible for controlling the flow of traffic based on a given flow’s priority, 
both from an internal perspective (within the kernel itself), and from a network 
perspective (prioritization and queuing of packets based on transmission priority). 


The following sections detail how traffic control is invoked, how traffic control settings 
can be checked, and how to programmatically modify how traffic control treats a 
given flow. 


Note Ownership of TC objects, such as flows and settings, are specific to a given 
application. As such, one application cannot inherit flow or filter objects from another 
object, not can an application change any such flows or settings it does not own. — 
Accordingly, all TC objects are deleted when an application (process) dies. 


How the RSVP SP Invokes TC 


The RSVP service and TC communicate in order to work together to provide overall 
QOS for a given sending flow. When an application requests QOS using the RSVP SP, 
the RSVP SP responds by initiating RSVP signaling and invoking kernel traffic control 
from local TC components (using the traffic control Interface). As such, traffic control and 
RSVP signaling are initiated concurrently upon flow setup. 


In this transitional period (presuming QOS_OBJECT_SD_MODE has not been 
specifically set) the reservation has not been established, and therefore traffic control is 
configured to transmit traffic associated with the flow’s specification, as follows: 


e BEST EFFORT traffic is transmitted with its QOS_ SD_ MODE set to borrow mode 
(TC_NONCONF _BORROW) 


e CONTROLLED LOAD traffic is transmitted with its QOS_SD_ MODE set to 
TC_NONCONF_BORROW 


e GUARANTEED traffic is shaped with its QOS_SD_MODE set to 
TC_NONCONF_SHAPE 
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Note The above default configuration can be overridden by supplying the 
QOS_OBJECT_SD_MODE object in the ProviderSpecific buffer. 


In this transitional period, all packets conforming to the flowspec for BEST_EFFORT and 
CONTROLLED LOAD are sent immediately with the appropriate traffic control marking, 
and nonconforming packets are sent immediately with their host and network priority 
demoted. Transmission settings for any given flow are aligned with the allowed sending 
rate specified by the system (which is in turn determined by settings in the appropriate 
FLOWSPEC). 


Sending applications can determine what the allowed sending rate is by querying the 
Allowed_Rate using SIO_CHK_QOS. More information about using SIO_CHK_QOS is 
provided in the section titled Using SIO_CHK_QOS. 


Once PATH messages arrive at the receiving host (or hosts; for simplicity, ongoing 
references will be singular), the host may request QOS provisioning for the flow in the 
form of RESV messages sent back toward the sender. When the RSVP SP on the 
receiver receives the RESV message, it communicates with traffic control to enable 

_ traffic control to update its transmission information, and if appropriate, to modify the 
BEST_EFFORT flow according to the reservation indicated in the RESV message. 


Note that it is possible to invoke traffic control without RSVP signaling, and to 
programmatically modify traffic control’s treatment of a flow. RSVP signaling can be 
suppressed on a given flow if the SERVICE_NO_QOS_ SIGNALING service type is 
specified, and traffic control can be suppressed on a given flow if the 
SERVICE_NO_TRAFFIC_CONTROL service type is specified. Additional control over 
the suppressing of RSVP signaling and traffic control can be achieved through the use of 
registry entries. For more information on controlling QOS through the use of registry 
entries, consult the Windows 2000 Resource Kit, available from Microsoft Press. 


Using SIO_CHK_QOS 


SIO_CHK_QOS can be used in conjunction with the WSAloctl function to obtain 
information on QOS traffic characteristics. During the transitional phase on the sending 
system between flow setup and the receipt of a RESV message (see How the RSVP SP 
Invokes TC for more information on the transitional phase), traffic associated with the 
flow is shaped based on service type (BEST EFFORT, CONTROLLED LOAD, or 
GUARANTEED). When the RSVP service on the sending host receives the RESV 
message, it communicates with traffic control to modify the BEST_EFFORT flow 
according to the change in ServiceType in the FLOWSPEC, and traffic control objects 
received in the RESV message. 


Certain applications may find the results of eee decird mode settings Pascsepuible: : 
such as a CONTROLLED LOAD flow’s nonconforming packets (in borrow mode) — 
potentially being discarded. To avoid unnecessary discarding of packets, applications 
can use SIO_CHK_QOS immediately following QOS invocation. The results of the call 
may require that the application defer data transmission until receipt of the RESV 
meeeece 
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Note that the default setting for SIO_CHK_QOS allows the application to send data as 
BEST_EFFORT before the reservation is in place. Network administrators in a given 
QOS-enabled network environment must explicitly override this setting on the ACS in 
order to exercise this control. 


Disabling Traffic Control 


Traffic control is invoked by default, and is done so immediately upon the receipt of a 
sending FLOWSPEC. Application programmers, however, can disable traffic control by 
using the SERVICE_NO_TRAFFIC_CONTROL service type. When the _ 
SERVICE_NO_TRAFFIC_CONTROL service type is used, traffic control is not invoked 
on the specified flow regardless of RSVP signaling. If QOS is reset (modified) without the 
SERVICE_NO_TRAFFIC_CONTROL flag, traffic control is invoked. 


aus Events 


Windows 2000 QOS makes QOS event information available to applications that register 
interest in obtaining event-related QOS information. Windows 2000 QOS makes the 
following event categories available to applications: 


e Policy-based or administratively based information that impacts QOS provisioning for 
a given flow. 


e Errors that occur upon setup, or during the life of a QOS-enabled flow. 
e Information regarding acceptance or rejection of QOS requests by the RSVP module 


or by the network. Keep in mind that rejection of a QOS request may indicate a 
transient failure, which may be subsequently corrected. | 


e Significant changes in the service quality provided by the network (when in contrast 
with previously negotiated QOS parameters), such as from flow preemption in the 
network. 


e Status regarding the presence of a QOS peer to send or receive a particular flow. 


Windows 2000 QOS provides this status information through the FD_QOS event suite. 
Applications that take advantage of QOS capabilities, whether sending or receiving data, 
should use FD_QOS events to maintain and monitor their QOS-enabled application. 
Registering interest in QOS events is done by listening for FD_QOS event notifications. 


It is important to realize that all FD_QOS events are edge-triggered. With edge-triggered 


events, a message is posted exactly once when a quality of service change occurs. 


Further messages are not forthcoming until the provider detects a further change in 
quality of service, or the application re-negotiates the flow’s Q0s. 
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For more information about event notification, consult the following knowledge base 
article: 


support.microsoft.com/support/kb/articles/Q 1 96/3/60.ASP 


Listening for FD_QOS Events 


QOS status is provided through FD_QOS events. Applications that either send or 
receive QOS-enabled data can listen for FD_QOS events by either of the following 
mechanisms: 


e Register for FD_QOS events using the WSAAsyncSelect or WSAEventSelect 
function. | 


e Perform an overlapped WSAloctl(SIO_GET_QOS) function call. 


Each of these approaches is explained in the following sections. 


Using WSAEventSelect or WSAAsyncSelect 


Applications that register their interest in receiving FD_QOS events can do so by 
enabling asynchronous event notification with either the WSAAsyncSelect or 
‘WSAEventSelect function. Information about how to do so can be found in the Windows 
Sockets 2 documentation. 


When registered for event notification using this mechanism, and an event notification 
occurs, an application can look up the status code (by using the _ 
WSAEnumNetworkEvents function, for example) and subsequently issue a 
WSAloctl(SIO_ GET _Q0S) function call to retrieve the cheper structure associated with 
the event. 


The associated Qos structure contains the current Qos es Applications 
should inspect the QOS parameters to determine the extent of the changes associated 
with the event notification. There are a couple of issues to consider when working with 
FD QOS events in this manner: 


e You must issue the WSAloctl(SIO_ GET_QOS) to reenable the FD_QOS event. 


e There may be multiple QOS status indications waiting for retrieval. Use the 
WSAloctl(SIO_GET_QOS) function call in a loop until SOCKET_ERROR is returned. 


Applications can also register their interest in FD _QOS events using poesvdaes 
WSAloctI(SIO_GET_QOS), as explained in Using Fees sete 
WSAloctl(SIO_GET_QOS). 


Using Overlapped WSAloctl(SIO_GET_QOS) 


Applications can register their interest in FD_QOS events by i issuing an overlapped 
WSAloctl(SIO_GET_QOS) function call. When an application takes this approach, an 
FD_QOS event invokes the completion function specified in the CompletionRoutine 
parameter of the WSAloctl function call, and the updated QOS structure is made 
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available in its output buffer. With this approach, the application could be developed to 
use the CompletionRoutine to act on the contents of the output buffer. The 
WSAloctl(SIO_GET_QOS) function request completes with QOS information that 
corresponds only to one direction (either the SendingFlowspec or the 
ReceivingFlowspec is valid, but not both). The FLOWSPEC that is invalid has its 
ServiceType value set to SERVICETYPE_NOCHANGE. 


Note Sending applications cannot call SIO_GET_QOS until a connection has 
completed. However, a receiving application can call SIO_GET_QOS as soon as it is 
bound. When using overlapped WSAlocti(SIO_GET_QOS) to monitor FD_QOS events, 
the RSVP SP also passes an RSVP_STATUS_INFO object in the ProviderSpecific 
buffer of the updated QOS structure. This enables applications to obtain extended status 
information about the FD_QOS event. 


Note If the output buffer associated with the WSAloctl function call is not sufficiently 
sized to contain the full QOS structure and the RSVP_STATUS_INFO object that is 
included in its ProviderSpecific buffer, the application will get WSA_ENOBUFS and can 
reissue the query. The required size is returned as an unsigned meger at the beginning 
of the output buffer. 


QOS Event Codes 


Applications that use the FD_QOS event suite to monitor QOS events have access to 
status and error codes associated with the event, as well as updated QOS parameters 
(in the QOS structure associated with the event). The following is a list of common 
QOS-related Windows Sockets 2 status and error codes. 


Event or error code Definition | 
WSA_QOS_RECEIVERS One or more RESV message has arrived. 
WSA_QOS_SENDERS One or more PATH message has arrived. 
WSA_QOS_NO_SENDERS There are no senders. 
WSA_QOS_NO_RECEIVERS There are no receivers. 
WSA_QOS_REQUEST_CONFIRMED Reservation has been confirmed. 
WSA_QOS_ADMISSION_FAILURE Error due to lack of resources. 
WSA_QOS_POLICY_FAILURE Rejected for administrative reasons. 
WSA_QOS_BAD_STYLE Unknown or conflicting style. 
WSA_QOS_BAD_OBJECT Problem with some part of the FLOWSPEC. 
WSA_QOS_TRAFFIC_CTRL_ERROR Problem with some part of the filter 

| specification. 
WSA_QOS_GENERIC_ERROR General error. 


For additional status and error codes, consult the Winsock2.h header file. 
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RSVP SP and RSVP 


Below the RSVP SP sits the Resource Reservation Protocol, or RSVP. RSVP is an 
lETF-standardized protocol that ferries quality of service provision requests between end 
nodes, and interacts with all RSVP-enabled network devices in the path between end 
nodes. The RSVP SP—which invokes and facilitates all aspects of Windows 2000 QOS, 
not just RSVP signaling—also enables application developers to fine-tune RSVP 
messages through the use of the ProviderSpecific buffer. Such fine-grained control of 
RSVP by an application enables the fine-tuning or special service requests to be made 
without depending on the RSVP SP to interpret conventional requests (through 
members in the QOS structure) and pass such requests down to RSVP. 


RSVP signaling is the primary mechanism employed by the RSVP SP to create an end- 
to-end QOS connection. When ServiceType in either the SendingFlowspec or 
ReceivingFlowspec member of the QOS structure is set to initiate Quality of Service 
over the connection in either direction (that is, when either parameter is set to a service 
type other than SERVICETYPE_BESTEFFORT or SERVICETYPE_NOTRAFFIC), the 
RSVP SP initiates RSVP signaling. 


Most application programmers will find that enabling an application to use the RSVP SP, 
which automatically initiates and maintains RSVP signaling on behalf of applications, is 
sufficient to enable their application to take advantage of QOS capabilities. 


For those interested in the specifics of RSVP signaling, and how to get more granular 
control over its parameters and notifications, the following sections outline general RSVP 
concepts as they interact with the RSVP SP. 


Basic RSVP Operations 


This section introduces basic RSVP operations, including: 


e How RSVP signaling is invoked by the RSVP SP. 
e How RSVP filters are defined and applied to RSVP SP Service Type specifications. 


Invoking RSVP 


There are two ways to invoke RSVP: 


e Using defaults, through the RSVP SP. 
e Overriding defaults, by using the RSVP_RESERVE_INFO object. 


RSVP signaling is invoked automatically when an application invokes the RSVP SP to 
provide QOS reservations on its behalf. The RSVP SP provides QOS reservations on 
behalf of an application when the service type in either the SendingFlowspec or 
ReceivingFlowspec members of the QOS structure is set to a service type other than 
SERVICETYPE_BESTEFFORT or SERVICETYPE_NOTRAFFIC. Note that there are a 
number of individual APIs that can invoke the RSVP SP. For more information, see 
Invoking the RS VP SP. 
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Another mechanism that an application developer can use to invoke RSVP, and to gain 
access to advanced RSVP features available in the QOS structure, is through the 
ProviderSpecific buffer in the QOS structure. 


The ProviderSpecific buffer can be used in conjunction with the 
RSVP_RESERVE_INFO object. When specific RSVP-based reservation information is 
specified in the RSVP_RESERVE_INFO object, RSVP SP-supplied default information 
is superseded by the information, enabling application developers to fine-tune the way 
RSVP handles reservation requests (and responses). For more information on using the 
RSVP_RESERVE_INFO object, see Using the RSVP_RESERVE_INFO Object. For 
more information about the FLOWSPEC structure, including which of its members can 
be defaulted, see FLOWSPEC. 


Using the RSVP_RESERVE_INFO Object 


The RSVP_RESERVE_INFO object enables application developers to specify granular 
QOS parameters directly to RSVP, providing a mechanism for fine-tuning RSVP 
reservations. To implement the object, you must pass a filled RSVP_RESERVE_INFO 
object to the RSVP SP using the ProviderSpecific buffer. The following members can 
be fine-tuned with the RSVP_RESERVE_INFO object: 


e RSVP Filter Style 

e RESV Confirmation Request 
e Policy Objects 

e List of flow descriptors 


Confirming RSVP Reservations 


The RSVP_RESERVE_INFO object enables a receiving application to be notified of the 
outcome of an RSVP reservation request. RSVP reservation confirmation is achieved by 
setting the ConfirmRequest member of the RSVP_RESERVE_INFO object to a 
nonzero value. This setting is necessary because RSVP network nodes are not required 
to automatically generate RSVP CONFIRMATION messages, per the RSVP 
specification. 


Until the presence of a reservation is discerned (Senders learn about the presence of a 
reservation by listening fora WSA_QOS_RECEIVERS event), data for the connection 
will be treated as BEST_EFFORT traffic, which provides a compelling reason for network 
programmers to enable RSVP confirmation immediately after a WSAConnect, 
WS<AJoinLeaf function call, or use of the SIO_SET_QOS IOCTL. 


Senders can query whether their application is allowed to send by using 


SIO_CHK_QOS. If the binary result of ALLOWED_TO_SEND is false (indicating that the 
application is not allowed to send) and the application chooses to send anyway, the 
traffic is treated as BEST_EFFORT. Once the RESV message arrives at the sender 


(triggering the RSVP confirmation), the RSVP SP on the sending host modifies traffic 


control service to match the service type in the RESV message, and the traffic is treated 
as per the service type. 
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RSVP confirmation requests are only useful for receiving applications. 


Disabling RSVP Signaling 

Both receiving applications and senders may disable RSVP signaling on a per-flow basis 
(a flow is a unidirectional QOS-enabled connection). Disabling RSVP signaling for a 
given flow is done by using the bitwise OR operator in the 

SERVICE_NO_QOS_ SIGNALING flag with the value in the ServiceType field of the 
ReceivingFlowspec member of the QOS structure. 


RSVP Reservation Styles 


~RSVP recognizes three reservation styles that define how RSVP-enabled network 
devices set up reservations along the path between an end-to-end QOS-enabled 
connection. RSVP reservation styles are also sometimes called reservation i a The 
three RSVP reservation styles are: 


e Fixed Filter (FF) 
e Wildcard Filter (WF) 
e Shared Explicit (SE) 


RSVP reservation styles either establish a distinct reservation for each upstream sender, 
or make a single reservation that is shared among all senders’ packets. The RSVP SP 
automatically selects an appropriate RSVP-reservation style based on the type of 
connection (unicast or multicast) as part of its RSVP invocation. Application 
programmers can override the RSVP SP’s selection of reservation style, overriding the 
setting that the RSVP SP provides, through use of the Style member of the 

~RSVP_ RESERVE_INFO object. For more information on owe this setting, see 
Overriding Default RSVP Filter Style Settings. 


Base RSVP Reservation Styles 

RSVP recognizes three base reservation styles. Note that not all RSVP reservation 
styles are available without direct interaction erougn the ProviderSpecific buffer) 
with RSVP. 


RSVP Fixed Filter 


The fixed filter (FF) RSVP reservation style implies a distinct reservation and an explicit 
sender. This contrasts with other reservation styles in that a reservation is made for 
individual senders, and the reservation is not shared with any other sender. 


The fixed filter style is appropriate (and its definition implied) for use with unicast — 
sessions. The RSVP SP uses the fixed filter for all TCP receivers, and for unicast UPD 
receivers attempting to establish a QOS-enabled connection. BP 
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RSVP Wildcard Filter 


The wildcard filter (WF) RSVP reservation style implies that a single reservation is 
shared among all senders in the session. The wildcard filter style is appropriate for use 
with applications such as audio conferencing, for example, in which only one or two 
speakers at a time can speak (in order for the audio conference to be meaningful); in 
which case only one reservation is necessary to service all participants. 


RSVP Shared Explicit 


The shared explicit (SE) RSVP reservation style is a hybrid of the other two RSVP 
reservation styles; with the shared explicit style, the receiving application is making a 
reservation which can be shared (explicitly) by selected senders. The shared explicit 
style is appropriate for applications such as a video conference in which, unlike the WF 
reservation, only participants who are explicitly listed benefit from the RSVP reservation. 


The RSVP SP does not use the shared explicit filter by default. Applications that want to 
use the shared explicit filter must set the Style member of the RSVP_RESERVE_INFO 
object to RSVP_SHARED_EXPLICIT_STYLE, and must specify the list of senders in 
flowdescriptors. 


It is important to note that the number of senders included in any individual Shared 
Explicit reservation should be limited to a reasonable number of senders (such as 10). If 
more than approximately 10 senders will be included in a given reservation, senders 
should use the WF reservation style. 


Default RSVP Filter Style Settings 


The RSVP SP sets RSVP reservation style based on the type of socket on which the 
reservation request is based. Default settings are applied to their corresponding 
connection types when the RSVP SP makes RSVP signaling requests on behalf of an 
application when there is no reservation, and when RSVP_DEFAULT_STYLE is 
specified in the Style member of the RSVP_RESERVE_INFO object. 


Note, however, that these default settings can be overridden by setting the Style 
member of the RSVP_RESERVE_INFO object to one of the other available RSVP filter 
styles. 


Unicast Receivers 


Applications that request QOS service provisions for unicast sessions are assumed to 
require the fixed filter (FF) RSVP filter style. While TCP receivers are always assumed to 
be unicast receivers, only UDP unicast receivers that use the WSAConnect function are 
provided with the Fixed Filter RSVP filter style; otherwise, UDP unicast receivers are 
provided with the wildcard filter (WF) RSVP reservation style. 


Multicast Receivers 


Applications that request QOS service provisions for multicast sessions are assumed to 
require the wildcard filter (WF) RSVP reservation style. 
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Use of the RSVP_DEFAULT_STYLE Filter Style 

The RSVP_DEFAULT_STYLE filter style enables an application developer to specify 
parameters in other members of the RSVP_RESERVE_INFO object without having to 
explicitly indicate (or override) the RSVP filter style applied by the RSVP SP. 


When the connection is TCP or connected UDP, specifying RSVP_DEFAULT_STYLE 
implements the fixed filter (FF) style. 


When the connection is multicast or unconnected UDP, specifying 
RSVP_DEFAULT_STYLE implements the wildcard filter (WF) style. 


Overriding Default RSVP Filter Style Settings 


Default RSVP filter style settings can be overridden through the use of the | 
RSVP_RESERVE_INFO object by specifying one of the following values in the Style 
member of the RSVP_RESERVE_INFO object, along with required flowdescriptors. 


The RSVP_FIXED_FILTER_STYLE Object 


The RSVP_FIXED_FILTER_STYLE object may be specified in the Style member of the 
RSVP_RESERVE_INFO object to override default settings of the wildcard filter (WF) 
RSVP filter style setting for multicast or unconnected UDP unicast receivers. This 
capability is useful when a multicast session has multiple senders; rather than accepting 
the default WF reservation that provides a shared reservation among all senders, you 
can use RSVP_FIXED_FILTER_STYLE to set up individual reservations for each 
sender. Another similar situation is when the receiver is using unconnected UDP to 
receive from multiple senders, in which a RSVP_FIXED_FILTER_STYLE can again be 
used to set up individual reservations for each sender. | 


Note that flowdescriptors must be specified when using the 
RSVP_FIXED_FILTER_STYLE object, and the NumFlowDesc member of 
RSVP_RESERVE_INFO is set to the number of senders, and FlowDescList of 

_ _RSVP_RESERVE_INFO is set to each sender's address/port. This is only appropriate 
when multiple senders are involved. 


The RSVP_WILDCARD_STYLE Object 


The RSVP_WILDCARD_STYLE object may be specified in the Style member of the 
-RSVP_RESERVE_INFO object to override default settings of the fixed filter cr) RSVP 
filter style setting for unicast receivers. 


Note that flowdescriptors must not be specified when using the 
RSVP_WILDCARD_STYLE object, such that the NumFlowDesc member of | 
RSVP_RESERVE_INFO is set to zero, and FlowDesctia! of RSVP_ RESERVE_ INFO is 
set to NULL. 


The RSVP_SHARED_EXPLICIT_STYLE Object 

The RSVP_SHARED_EXPLICIT_STYLE object may be specified in the Style member 
of the RSVP_RESERVE_INFO object to override default RSVP filter style settings. The 
RSVP_SHARED_EXPLICIT_STYLE object is used to create an RSVP Shared Explicit 
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(SE) reservation (see Base RSVP Reservation Styles). Note that the only way to create 
connections that use the shared explicit (SE) RSVP filter style is through this 
mechanism. 


The RSVP_SHARED_EXPLICIT_STYLE object cannot be applied tc to TCP receivers or 
to connected UDP receivers. 


When the RSVP_SHARED EXPLICIT STYLE is used, the flow’s resources are shared 
between all senders listed in the FilterSpec. Also, when using the 
RSVP_SHARED_EXPLICIT_STYLE object, flowdescriptors must be specified, such that 
the NumFlowDesc member of RSVP_RESERVE _ INFO is set to 1, and FlowDescList 
of RSVP_RESERVE_INFO is not set to NULL. 


It is important to note that the number of senders included in any individual Shared 
Explicit reservation should be limited to a reasonable number of senders (such as 10). If 
more than 10 senders will be included in a given reservation, senders should use the WF 
reservation style. | 


Generating Multiple Fixed Filter Reservations in a Single Reservation 


It may be useful in certain situations to enable a receiver to reserve mutually exclusive 
flows for multiple, explicitly identified sources. This is achieved by generating multiple 
fixed filter (FF) RSVP reservations in a single reservation. 


To do this, specify RSVP_FIXED_FILTER_STYLE in the Style member of the 
RSVP_RESERVE_INFO object, followed by a list of multiple flowdescriptors. So for n 
explicitly identified sources, the NumFlowDesc member of the RSVP_RESERVE_INFO 
object is set to n, and the FlowDescList member of the RSVP_RESERVE_INFO object 
is set to n sender addresses/ports. 


Note that this cannot be done with TCP receivers, as TCP receivers are assumed 
connected to a single-peer sender. This should not be applied to UDP receivers that 
have been connected using the WSAConnect function. In these cases, the transport 
discards data from all senders other than the sender specified in the WSAConnect 
function call. 


Mapping RSVP Sp Parameters to RSVP 


In order to provide quality of service parameters from the RSVP SP to RSVP. there must 
be some mechanism to translate parameters that the application provides in the QOS 


_ structure to RSVP. Passing RSVP-requisite service quality parameters, based on 


information provided by the application to the RSVP SP, is done through mapping. 


The information provided to RSVP is derived from the SendingFlowspec and 
ReceivingFlowspec members of the FLOWSPEC structure, itself a member of the QOS 
eee: 
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RSVP PATH and RESV Messages 


RSVP establishes QOS-enabled connections through the use of PATH and RESV 
messages. A short explanation of each, and how they pertain to Windows 2000 QOS 
and the RSVP SP is merited. For a thorough explanation and discussion of RSVP PATH 
and RESV messages, consult IETF RFC 2205. 


When a QOS-enabled connection is established and RSVP signaling is triggered (see 
Invoking RSVP), the sender and receiver(s) play specific roles in the establishment of an 
RSVP session: 


¢ The sender emits PATH messages toward the receiver (or receivers). 


e The receiver waits until the PATH message corresponding to the flow arrives, then 
_ issues a RESV message. 


~ The information contained in the PATH and RESV messages is derived from the 
FLOWSPEC structures associated with the SendingFlowspec and 
ReceivingFlowspec members of the QOS structure. 


Transmission of RSVP PATH and RESV Messages 


When a PATH message is received, the RSVP SP creates an RSVP session and 
associates a PATH state (based on the PATH message) with the RSVP session. The 
RSVP SP sends RESV messages once it determines that the PATH state exists for a 

- session that matches a socket for which receiving QOS is indicated. In the absence of a 
received PATH message, the RSVP SP creates an RSVP session using QOS 
parameters (and thereby, QOS is invoked) on a receive socket. In this latter case, PATH 
state is not associated with the session until a matching PATH message is received. 


The transmission of RESV messages, therefore, may be triggered by the following — 
circumstances: 


e Upon receipt of a PATH message that matches the session associated with a 
preexisting socket. 


e Upon creation of a socket that matches the session associated with a preexisting 
| PATH state. 


RSVP PATH Message Parameters 


RSVP PATH messages derive their RSVP sender Tspec from the SendingFlowspec 
member of the QOS structure (the SendingFlowspec member of QOS is itself a 
FLOWSPEC structure). : 


The following table outlines the information required to begin transmission of RSVP 
PATH messages, and how the information is derived from the QOS structure or other 
information provided by the sender. The RSVP PATH pales discussed serve the 
following purposes. 


768 


Volume 1 Winsock and QOS 


e SenderTspec contains QOS parameters for sent traffic. 
e SenderTemplate contains the sender’s address. 
e Session contains the destination of the sent traffic. 


RSVP PATH parameter Equivalent receiver—based parameters 

SenderTspec SendingFlowspec member of the QOS structure. 

SenderTemplate Source IP address/port to which sending socket is — 
bound. 

Session Destination IP address/port and protocol identifier to 


_ which the socket is sending (Ssockaddr_in). 


Note that the RSVP session parameter includes specification of the protocol identifier 
can be UDP or TCP. The type of socket on which the QOS-enabled connection is being 
invoked determines the protocol identifier. 


RSVP RESV Message Parameters 


RSVP RESV messages derive their RSVP FLOWSPEC parameters from the 
ReceivingFlowspec member of the QOS structure (the ReceivingFlowspec member of 
QOS is itself a FLOWSPEC structure). 


The following table outlines the information required to begin transmission of RSVP 
RESV messages, and how the information is derived from the QOS structure or other 
information provided by the receiver. The RSVP RESV parameters discussed serve the 
following purposes: 

e Flowspec contains desired QOS parameters for traffic to be received. 


e Filterspec contains the source or sources from which QOS-enabled traffic will be 
received. 


e Session contains the destination of the sent traffic. 


RSVP RESV parameter Derived from the following Winsock parameter 


flowspec ReceivingFlowspec member of the QOS structure 
: or the ProviderSpecific buffer. 


Filterspec (source(s) from which Address(es) of peer(s) from which the socket is 


QOS traffic will be received)*. receiving. | 
Session (destination of sent Local IP address and port to which the receiving 
traffic). socket is bound (unicast), or multicast session 


address to which the socket has joined (multicast). 


-* Strictly speaking, RESV messages can be generated without knowledge of the sender’s address. These 
type of RESV messages are said to be WF style, meaning that they apply to all senders in the session. 


The WF reservation style RESV messages do not have any filterspecs, so receivers 
need not supply the sender an IP address. 
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Tspec, FlowSpec, and Adspec 


RSVP transmits request information for a QOS-enabled connection with RSVP PATH 
and RESV messages. Within such PATH and RESV messages, certain values are used 
to represent traffic and requested QOS parameters that enable a sender and receiver to 
establish service quality parameters for a given flow: 


e The sender Tspec (T representing traffic) specifies parameters available for the flow. 
Both senders and receivers use Tspec (SenderTspec and ReceiverTspec, 
respectively). 


e The FLOWSPEC specifies requested QOS parameters, and is used by the receiver in 
RESV messages. 

e The Adspec (ad for advertisement) enables QOS-enabled network devices in the path 
between sender and receiver to advertise their service capabilities, resource 
availability, and transmission characteristics. 


RSVP Tspec 


Both senders and receivers use Tspec, as part of SenderTspec and Receiverflowspec, 
respectively. 


Sender provides the Tspec to describe the traffic it will originate, and the receiver 
provides the flowspec to describe the reservation it needs. 


The RSVP Tspec derives its parameters from the SendingFlowspec member of a QOS 
structure (SendingFlowspec is of type FLOWSPEC). | 


The following table explains how members in SendingFlowspec map to Tspec 
parameters. 


SendingFlowspec Parameter Tspec 

TokenRate TokenBucketRate 

TokenBucketSize TokenBucketSize 

PeakBandwiath PeakRate 

MinimumPolicedSize MinimumPolicedUnit 

MaxSduSize MaximumPacketSize 
_ DelayVariation 

Latency 

SenderTspec Specifics 


The following items are specific to a sender’s use of the RSVP Tspec in PATH 
messages: 


° if MaxSduSize is not specified in the Tspec included in the sender's PATH message, 
the RSVP SP will default to a value of 1,500 bytes. 


e If MinimumPolicedSize is not specified in the Tspec included in the sender’s PATH 
message, the RSVP SP will default to a value of 128 bytes. 
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Receiver Flowspec Specifics 


For receivers, the contents of the RSVP flowspec varies depending on requested service 
type in the following ways: 


e¢ CONTROLLED LOAD service contains a Tspec. 
e GUARANTEED service flowspec contains a Tspec and an Rspec. 


CONTROLLED LOAD Service 

Receivers requesting CONTROLLED LOAD service may decide to specify only (but at 
least) the ServiceType parameter in ReceivingFlowspec, setting remaining parameters 
to QOS_UNSPECIFIED, in which case the RSVP SP copies the SenderTspec from the 
matching PATH message into the ReceiverFlowspec sent with the corresponding RESV 
message. In order to specify additional parameters in the ReceiverFlowspec (allowing 
remaining flow parameters set to QOS_ UNSPECIFIED to be derived from the 
SenderTspec), an application may provide values for other ReceivingFlowspec 
parameters. 


GUARANTEED Service 

When a receiver requests GUARANTEED service, the RSVP SP copies SenderTspec 
from the matching PATH message into the ReceiverFlowspec sent with the 
corresponding RESV message. 


RSVP Rspec 


The RSVP Aspec specifies requested QOS parameters, and is used by the receiver in 
RESV messages to transmit requested reservation parameters only when 
GUARANTEED service is specified by the application. The Rspec derives its parameters 
from the ReceivingFlowspec member of a QOS structure (ReceivingFlowspec is of 
type FLOWSPEC). 


The following table explains how parameters in ReceivingFlowspec map to Tspec 
parameters. 


ReceivingFlowspec parameter Rspec 


TokenRate — Rate 

TokenBucketSize 

PeakBandwidth 

MinimumPolicedSize 

MaxSduSize 

DelayVariation | Dela ySlackTerm 

Latency | 

The application specifying GUARANTEED service is expected to provide two of the 
three parameters, in the following combinations. 
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e TokenRate 

e DelayVariation 
e DelayVariation 
e Latency 


If an application fails to specify two of the three required parameters, the RSVP SP infers 
appropriate values based on the corresponding PATH message(s). The following table 
explains how the provided parameters are used by the RSVP SP to construct the RSVP 


Rspec. 
Application specifies: RSVP SP constructs Rspec: 
TokenRate and DelayVariation Rate is copied from TokenRate 


DelaySlackTerm is copied from DelayVariation 
Latency parameter ignored 


DelayVariation and Latency Rate parameter of Rspec calculated based on 
: DelayVariation and Latency and other 
parameters obtained from Adspec 


RSVP Adspec 

Each RSVP PATH message includes an Adspec, which enables QOS- enabled network 
devices in the path between sender and receiver to advertise the services they support, 
their resource availability and transmission characteristics. Such information can be 
useful in helping the receiving application select FLOWSPEC. 


Mapping QOS Call Sequences to RSVP_ 


RSVP signaling is invoked once a series of QOS calls that initiate QOS activity are 
called. Such call sequences tend to differ based on whether an application is a sender or 
receiver, and for that reason, senders and receivers are discussed separately. 


Often, applications will be both sender and receiver, in which case both sender and 
receiver call sequences may apply. : 


Sending Applications 
_In order for the RSVP SP to invoke RSVP processing and signaling, the following 

information must be available: | 

e Peer address (the receiver's address). This enables RSVP to create its session 
object. | 

e Source address (the sender’s local address). This enables Rsvp to create its 
SenderTemplate object. ss 

¢ QOS parameters in the form of a SendingFlowspec (a member of the QOS 
structure). This enables RSVP to generate its sender Tspec object. _ 
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The means by which the RSVP SP derives information necessary to satisfy those three 
requirements is outlined in the following table. 


Sender type 
UDP unicast 


Session information 
derived from: 


Destination address and 


SenderT. emplate derived from: 


Local port determined by a RSVP SP 


sender 


UDP multicast 
sender 


TCP unicast 
sender 


pages: 


port specified in the name 
parameter of the 
WSAConnect function. 


Multicast IP address and 
port as specified in the 
name parameter of the 
WS<AJoinLeaf function. 


Peer (destination) address 
and port as determined by 
a Call to the getpeername 
function, following 

connection establishment. 


-e@ UDP unicast senders 


e UDP multicast senders 
e TCP unicast senders 


UDP Unicast Senders | 
The RSVP SP derives information for the initiation of RSVP processing and signaling for 


UDP unicast senders based on the following table. 


call to the getsockname function. 


For sockets bound explicitly by the 
application, to a specific address, the 
RSVP SP calls the getsockname 
function to get the local address/port. 


For sockets bound by the application 
to INADDR_ANY, the RSVP SP gets 
the local address by issuing a routing 
interface query on the destination 
address (as obtained from the 
application’s call to the WSAConnect 
or WSAJoinLeaf function). 


Same as above. 


Local address and local port 
determined by call to the 
getsockname function following 
connection establishment. | 


‘Details of each of these sender types are outlined individually in the following reference 
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Session information 


Sender type derived from: SenderTemplate derived from: 
UDP unicast Destination address and Local port determined by a RSVP SP 
sender port specified in the name call to the getsockname function. 
| parameter ofthe For sockets bound explicitly by the 
WSAConnect function. application, to a specific address, the 


RSVP SP calls the getsockname 
function to get the local address. 


For sockets bound by the application 
to INADDR_ANY, the RSVP SP gets 
the local address by issuing a routing 
interface query on the destination 
address (as obtained from the 
application’s call to the WSAConnect 
or WSAJoinLeaf function). 


Unicast UDP senders typically call the WSAConnect function to invoke RSVP 
processing and signaling. For sockets that have been bound using INADDR_ANY, the 
RSVP SP uses the peer address to determine the local address to use SenderTemplate 
by issuing a routing interface query to the underlying transport service provider. This 
approach returns the address of the local interface used to reach the specified peer. 


Typically, the WSAConnect function call includes sending QOS parameters 
(SendingFlowspec). Alternatively, the sending application may use the 
WSAloctl(SIO_SET_QOS) function/opcode call to provide sending QOS parameters to 
the RSVP SP, either before or after the WSAConnect function call. 


RSVP processing begins as soon as the RSVP SP knows the peer address (from which 
it may also determine the local bound address) and the sending QOS parameters. 


_ Application programmers can also choose to use unconnected UDP sockets using 
Wsaloctl(SIO_SET_QOS) by specifying aQ@OS_OBJECT_DESTADDR object in the 
ProviderSpecific buffer of the QOS structure. In this scenario, the session information is 
derived from the QOS_OBJECT_DESTADDR object. 


Note for unconnected UDP sockets An application may choose to use unconnected 
UDP sockets by specifying a Q@OS_OBJECT_DESTADDR object in the 7 
ProviderSpecific buffer of the QOS structure. In this case, the session information is 
derived from the QOS_OBJECT_DESTADDR object. | 


_ UDP Multicast Senders 


The RSVP SP derives information for the initiation of RSVP signaling for UDP multicast 
senders based on the following table. 
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Session information 


Sender type derived from: SenderTemplate derived from: 
UDP multicast Multicast IP address and © Local port determined by RSVP SP 
sender port as specified in the call to the getsockname function. 
| name parameter of the For sockets bound explicitly by the 
WSAdJoinLeaf function. application, to a specific address, the 


RSVP SP calls the getsockname 
function to get the local address. 


For sockets bound by the application 
to INADDR_ANY, the RSVP SP gets 
the local address by issuing a routing 
interface query on the destination 
address (as obtained from the 
application’s call to the WSAConnect 
or WSAJoinLeaf function). 


Multicast UDP senders typically call the WSAJoinLeaf function to invoke RSVP 
signaling. The WSAJoinLeaf function call provides the destination multicast session 
address, and may also be used to provide QOS parameters through its LPQOS 
parameter. If QOS parameters are not provided with the call to WSAJoinLeaf, they must 
be provided separately with a call to the WSAloctl(SIO_SET_QOS) function/opcode 
pair. The RSVP session object included in the corresponding PATH messages is derived 
from the multicast session address. 


For sockets that have been bound using INADDR_ANY, the RSVP SP uses the 
multicast session address to determine the local address used in SenderTemplate by 
issuing a routing interface query to the underlying transport service provider. This 
approach returns the address of the local interface used to reach the specified peer. 
RSVP processing begins as soon as the RSVP SP knows the peer address and the 
sending QOS parameters. 


TCP Unicast Senders 


The RSVP SP derives information for the initiation of RSVP processing and signaling for 
TCP unicast senders based on the following table. 


Session information 


Sender type derived from: oe SenderTemplate derived from: 

TCP unicast Peer (destination) address — Local address and local port 

sender and port as determined by determined by call to the 
acallto the getpeername §getsockname function following 
function, following connection establishment. 


connection establishment. 
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Generally, sockets are connected through the interaction of an active and passive peer; 
the active peer issues a WSAConnect function call, and the passive peer issues a 
WSAAccept function call. In most circumstances the receiver is the active peer, the 
sender the passive peer. This page assumes the sender is the passive peer; for cases 
where the sender is the active peer, refer to TCP unicast receivers. 


Upon calling the WSAAccept function, the TCP unicast sender can gather QOS 
parameters through the WSAAccept function’s callback function, but in order to do so, 
the application must complete the callback function with status CF_ACCEPT. The RSVP 
SP does not use the ProviderSpecific buffer when calling the leith function’s 
callback function. | 


Applications may alternatively set QOS surenieior on the socket (or any parameters 
that require use of the ProviderSpecific buffer) through the use of the 
WSAloctl(SIO_SET_QOS) function/opcode call. However, if the application has 
previously associated QOS parameters with the socket by calling the _ 
WSAloctl(SIO_SET_QOS) function/opcode pair, completion of the callback function 
may modify QOS parameters unless the ServiceType parameters in the corresponding 
FLOWSPEC structures are set to SERVICETYPE_NOCHANGE. 


The application may also set QOS parameters on the listening socket prior to the call to 
WSAAccept, and these settings are inherited by the accepted socket, but any 
parameters set in the WSAAccept function’s callback function take precedence. RSVP 
processing begins as soon as the RSVP SP knows the peer address, the address to 
which the socket is locally bound, and the sending QOS parameters. 


Receiving Applications 


For the RSVP SP to invoke RSVP processing and signaling, the receiving application is 
required to provide the following information: 


e QOS parameters, through the use of the ReceivingFlowspec member of the QOS 
structure. Receiving applications generally provide such QOS parameters in a call to 
the WSAConnect or WSAJoinLeaf functions, or in a call to the 
WSAloctl(SIO_SET_QOS) function/opcode pair. 


For receiving applications, the RSVP SP must create a session object, and in certain 
cases must create a filterspec object (filterspec selects a subset of the senders by 
specifying their address) for placement into its RESV messages. These objects are 
generally matched to the PATH state (which itself is derived from corresponding PATH 
messages). In order to limit ee of the PATH state, the RSVP sP needs the © 
following information: 


-e Peer address or addresses (the source address). This enables RSVP: to limit RSVP 
sessions for which RESV messages are sent. 


e Local address. The RSVP SP uses the local address to *atéh received PATH 
_ messages and to select the interface on which to send out the RESV message. 
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Transmission of RESV messages begins as soon as the RSVP service has sufficient 
information. | | 


Details of each of these receiver types are outlined individually in the following sections: 


e UDP unicast receivers 
e UDP multicast receivers 
e TCP unicast receivers 


UDP Unicast Receivers 


UDP unicast receivers can initiate a QOS-enabled connection by providing QOS 
parameters to the RSVP SP using either of the following methods: 


e Acall to the WSAConnect function 
e Acall using the WSAloctl(SIO_SET_QOS) function/opcode pair. 


Using WSAConnect 


A UDP unicast receiver should use the WSAConnect function only if it wants to receive 
from a single sender; using WSAConnect causes traffic received from other senders to 
be discarded. In order to receive traffic from multiple senders using the WSAConnect 
function, a separate socket must be created for each sender. By using the WSAConnect 
function as a UDP unicast receiver, the application provides a peer address and, in 
doing so, selects a specific sender. 


When a UDP unicast receiver uses the WSAConnect function, the RSVP SP sends 
RESV messages only when the PATH state exists for the specified sender, and uses the 
included peer address to compose fixed filter style (FF) RESV messages. 


Note that using the WSAConnect function may cause the RSVP SP to cease sending 
RESV messages that were triggered in a previous call to the WSAloctl(SIO_SET_QOS) 
function/IOCTL pair; this is because PATH state, though it may have existed for some 
sender, may not have existed for the sender specified in the WSAConnect function call. 


Using WSAloctl(SIO_SET_QOS) — 


A UDP unicast receiver can use the WSAloctl(SIO_SET_QOS) function/IOCTL pair to 
indicate receiving QOS parameters, after which the RSVP SP begins transmitting RESV 
messages for any matching PATH state. Since the WSAloctl(SIO_SET_QOS) 
function/IOCTL pair does not associate a peer address with the socket (unless the 
ProviderSpecific buffer is used to specify a particular sender), the socket will match 
PATH state of any sender in this RSVP session. | 


When the WSAloctl(SIO_SET_QOS) function/IOCTL pair is used by a UDP unicast 
receiver, the RSVP SP transmits wildcard filter (WF) style RESV messages. Note that 


_ WEF RESV messages are used for unconnected UDP sockets only; connected UDP 


sockets result in Fixed Filter (FF) style reservations. 
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Combining WSAConnect and WSAlocti(SIO_SET_QOS) 


A UDP unicast receiver may call both the WSAloctl(SIO_SET_QOS) function/IOCTL 
pair and the WSAConnect function in any order. In either case, the RSVP service 
begins sending RESV messages as soon as the indicated QOS parameters match a 
PATH state. 


If the WSAloctl(SIO_SET_QOS) function/IOCTL pair is called before the WSAConnect 
function, the RSVP SP initially sends wildcard filter (WF) RESV messages, presuming a 
matching PATH state. Subsequently (upon calling of the WSAConnect function, its 
specified peer, and a matching PATH state) the RSVP SP sends a RESVTEAR 
message for the WF style reservation followed by fixed filter (FF) style RESV messages. 


Calling the WSAloctl(SIO_SET_QOS) function/IOCTL pair subsequent to a call to the 
WSAConnect function does not negate the selection of a specific sender. Therefore, 
while the WSAloctl(SIO_SET_QOS) function/IOCTL pair is a useful method of altering 
RESV messages (such as altering QOS parameters, or terminating RESV messages 
altogether by indicating BEST_EFFORT), its use does not cause the RSVP SP to send 
wildcard filter (WF) style RESV messages. 


UDP Multicast Receivers 
UDP multicast receivers are expected to do the following: 


e Create UDP sockets using the WSASocket function. 
e Indicate that they are multicast receivers in the accompanying (WSASocket) flags. 
e Call the WSAJoinLeaf function to indicate the multicast session they want to join. 


UDP multicast receivers can indicate QOS parameters either through their call to the 
WS<AJoinLeaf function, or through the use of the WSAloctl(SIO_SET 409) 
~ function/IOCTL pair. 


The RSVP SP does not send RESV messages for UDP multicast receivers until a 
multicast session address is unambiguously specified through the use of a 
WSAJoinLeaf function call. The RSVP SP does not use parameters with which the 
socket is bound; since no peer is specified, the RSVP service sends a WF style RESV 
message only when it has a PATH state from at least one sender. 


A UDP unicast receiver may call both the WSAloctl(SIO_SET_QOS) function/IOCTL 
pair and the WSAJoinLeaf function in any order. In either case, the RSVP service 
begins sending RESV messages as soon as there is a sender in the multicast session. 
However, with multicast receivers the matching PATH state will only be found if a 
multicast socket has been created with a matching multicast session address. 


Joining Multiple Multicast Groups ona Single Socket 


When a UDP multicast receiver joins multiple multicast groups ona single socket, the 
RSVP SP sends RESV messages for all groups for which there is a matching PATH 
state. Qos parameters are obtained separately from the ReceivingFlowspec included 


778 


Volume 1. Winsock and QOS 


in individual WSAJoinLeaf function calls made for each multicast group. However, if the 
WSAloctl(SIO_SET_QOS) function/IOCTL pair is called, its specified QOS parameters 
are applied to all presently joined multicast groups. 


TCP Unicast Receivers 


TCP receivers are generally the active peer in a TCP connection. TCP unicast receivers 
are therefore expected to initiate a QOS-enabled connection by providing QOS 
parameters to the RSVP SP using one of the following methods: 


© A call to the WSAConnect function 
e Acall using the WSAloctl(SIO_SET_QOS) function/opcode pair. 


The RSVP SP uses the address specified in the WSAConnect function call to specify 
the peer sender's address, which enables RSVP to compose its filterspec for fixed filter 
(FF) style RESV messages. The RSVP SP begins RSVP processing. 


RSVP will start signaling as soon as the RSVP SP knows the receiving QOS 
parameters, and those parameters match a PATH state; PATH state only matches if the 
associated socket’s session address matches the bound address and its 
SenderTemplate matches the peer address. 


If the receiving socket is bound using INADDR_ANY, the bound address cannot be 
determined until the WSAConnect function is called. Under this circumstance, RESV 
messages are delayed until, following connection establishment, the RSVP SP 
automatically calls the getsockname function to determine local address. 


Receiver Reservation Semantics 


The process of joining RSVP sessions includes making appropriate function calls 
particular to the type of RSVP session an application wants to join. Due to their inherent 
differences, and the difference in the way each handles sockets, unicast (both TCP and 
UDP) and multicast sessions are best discussed individually. To generalize, the following 
are usually true: 


e Unicast sessions usually include use of the WSAConnect function. 


e Multicast sessions generally use the WSAJoinLeaf function (and sendto for multicast 
senders). 


e Both unicast and multicast can use the WSAloctl(SIO_SET _QOS) 
functioh/opeode pair. 


Each of these common methods for joining RSVP sessions is discussed individually. 


Using WSAConnect to Join Unicast RSVP Sessions | 


The WSAConnect function is generally used by unicast receivers to join RSVP 
sessions. The behavior is somewhat different with TCP sessions and UDP unicast 
sessions. | 
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TCP Sessions 


The use of the WSAConnect function with RSVP-enabled TCP sessions is fairly simple, 
if somewhat stringent, because parameters match quite well between parameters 
associated with the WSAConnect function and parameters necessary for RSVP to 
operate. The following table illustrates which conditions of a TCP socket (left column) 
correspond to RSVP conditions (right column) that enable the TCP socket to join the 
session. 


TCP Socket is: RSVP session is joined: 


Not bound, or is bound and not Never 
connected (the WSAConnect 
function is not issued) 


Bound and connected If both of the following conditions are true: 

| | a The port and address specified in any TCP session 
matches the socket’s bound port and address. 
SenderTemplate, which is specified in PATH state | 


associated with the session, matches the connected 
peer’s port and address. 


UDP Unicast Sessions 


The use of the WSAConnect function with RSVP-enabled UDP unicast sessions is less 
stringent than its use with TCP sessions, largely due to the fact that it is not always 
possible to determine unique addresses associated with a UDP socket. The following 
table illustrates which conditions of a UDP unicast socket (left column) correspond to 
RSVP conditions (right column) that enable the UDP unicast socket to join the session. 
These mappings do not apply to UDP multicast sessions. 


UDP unicast socket is: RSVP session is joined: 


Not bound and not connected. Never 


Bound using INADDR_ANY, and If the port specified in any UDP session matches 
not connected (the WSAConnect the socket’s bound port. 
function is not issued). 


Bound using a specific address and __ If the port and address specified in any UDP 


not connected. | session matches the socket’s bound ‘port and 

| | _ : address. | 
Bound using INADDR_ANY, and If both of the following conditions are true: 
connected. | | The port specified in any UDP session matches 


the socket’s bound port. 


SenderTemplate, which is specified in PATH 
state associated with the UDP session, matches 
the connected peer’s port and address. 


(continued) 
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(continued) 

UDP unicast socket is: RSVP session is joined: 

Bound using a specific address and __If both of the following conditions are true: 

connected. The port and address specified in any UDP 
session matches the socket’s bound port and 
address. 


SenderTemplate, which is specified in PATH 
state associated with the session, matches the 
connected peer’s port and address. 


Using WSAJoinLeaf to Join Multicast RSVP Sessions 


Multicast UDP receivers are expected to create the multicast UDP socket using the 
WSASocket function, and indicate that they are multicast receivers in the accompanying 
(WSASocket) flags. If multicast UDP sockets don’t use the WSASocket function (and 
associated multicast flags), the RSVP SP may not be able to determine that the socket is 
multicast, and therefore may send undesired RESV messages based on unicast 
matching rules described in the Using WSAConnect to Join unicast RSVP Sessions 
section. 


The following table illustrates which conditions of a UDP multicast socket (left column) 
correspond to RSVP conditions (right column) that enable the UDP multicast socket to 
join the session (note these mappings do not apply to UDP unicast sessions). 


UDP multicast socket is: RSVP session is joined: 


Not joined to a specific multicast group Never 
(the WSAJoinLeaf function is not 


issued). 
Joined to a specific multicast group The multicast address specified in any UDP 
(using the WSAJoinLeaf function). session matches the multicast address 


specified in the WSAJoinLeaf function call. 


Applications are required to use the WSAJoinLeaf function call before sending or 
receiving multicast traffic, and are required to set the dwFlags parameter of the 
WSAJoinLeaf function to JL_LSENDER_ONLY, JL_RECEIVER_ONLY or JL_BOTH, to 
indicate the direction in which QOS service is requested. 


It is important to note that alternate multicast semantics, such as simply sailing the 
sendto function with a multicast address (for sending) or using IP_ADD _MEMBERSHIP 
(for receiving) do not invoke QOS service, even if the IOCTL is issued. 
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Use of Sendto and WSASendTo by Multicast Senders 


Senders that join multicast sessions using the WSAJoinLeaf function are required to call 
the sendto or WSASendTo function with the correct multicast session address to send 
data to the multicast session (even though the multicast session address is already 
provided with the WSAJoinLeaf function call). If the sending application calls the sendto 
or WSASendTo function specifying a multicast session address other than the address 
specified with the WSAJoinLeaf function call, the data will not receive QOS 

provisioning. This requirement is due to the fact that the sender’s RSVP service 
generates the RSVP session based on the multicast session address specified in the 
call to the WSAJoinLeaf function. 


Also note that QOS-enabled applications should only call the sendto or WSASendTo 
function when acting as a multicast sender. Unicast (UDP or TCP) sender applications 
must specify their destination address using WSAConnect, and it is sufficient for that 
application to use the send or WSASend function calls, rather than the sendto or 
WSASendTo functions. 


Using WSAlocti(SIO_SET_QOS) During RSVP Sessions 


The use of WSAloctl(SIO_SET_QOS) is often unnecessary; the use of connection- 
oriented Windows Sockets function calls (such as the WSAConnect function) is 
generally sufficient for providing the RSVP SP (and therefore RSVP) with requisite QOS 
parameters. 


One exception is when a UDP application receives from multiple senders, in which case 
the WSAloctl(SIO_SET_QOS) function/opcode pair must be used to specify QOS 
parameters to avoid limiting the socket to receive traffic from a single sender (as the use 
of a connection-oriented function call such as WSAConnect would do). This is a 
limitation of Windows Sockets 2. 


Another exception is when a UDP transmit uses the sendto function to transmit data to 
one or more receivers through an unconnected socket (Microsoft® NetMeeting™ 
version 2.1 is an example of such an application). In this circumstance, the sending 
application must do the following in order to invoke QOS provisioning: 


e Supply the RSVP SP with one or more appropriate SendingFlowspec(s) by issuing 
one or more SIO_SET_QOS IOCTLs. 


e Provide the RSVP SP with the destination address by issuing a 
QOS_OBJECT_DESTADDR object in the ProviderSpecific buffer. 


The WSAloctl(SIO_SET_QOS) function/opcode pair is also useful for modifying QOS 
parameters subsequent to the establishment of the connection with a connection- _ 
oriented function call. This functionality also enables an application to separate the 
specification of QOS parameters from the determination of local and peer addresses 
implicit in making a connection-oriented function call. 
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CHAPTER 15 


QOS API Reference 


~ QOS Functions 


This section contains an alphabetical list of QOS functions. 


e WPUGetQOSTemplate 

¢ WSAGetQOSByName 

e¢ WSCinstallQOSTemplate 

¢ WSCRemoveQOSTemplate - 
e WSPGetQOSByName 


WPUGetQOSTemplate 


The WPUGetQOSTemplate function retrieves a QOS template for a particular service 
provider. Eas 


Parameters | ee | 
IpProviderld | oo ae 
[in] Pointer to a provider selected—globally unique identifier (GUID). 
IpPQOSName 
[in] Specifies the QOS template name. 


IpPQOS. 
[out] Pointer to a QOS structure. 


Return Values 


lf WPUGetQOSTemplate succeeds, the return value is zero. If the function fails, the 
return value is SOCKET_ERROR. For extended error information, call 
WSAGetLastError. 
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Remarks 


The WPUGetQOSTemplate function retrieves a QOS-named template containing the 
associated QOS structure. If /oProviderld is NULL, WPUGetQOSTemplate attempts to 
find the QOS-named template in the global list of QOS names. Otherwise, 
WPUGetQOSTemplate searches the template list specific to the service provider 
indicated by /pProviderld. 


The /oQOS parameter can include a ProviderSpecific buffer for retrieval with the basic 
QOS structure. In this case, the ProviderSpecific buffer must be large enough to hold 
the provider-specific information stored in the template; otherwise 
WPUGetQOSTemplate returns WSAENOBUFS. 


Error Codes 

Error Code Meaning 

WSAEFAULT _ The IpQOS or IpQOSName parameter is not a valid part of the 
| user address space. 

WSAEINVAL The specified /oProviderld is invalid, or the /OQOS template is 

invalid. 
WSA_NODATA The specified QOS name could not be found. 
WSAENOBUFS The provider-specific buffer is too small. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qosname.h. 

Library: Use Qosname.lib. 


QOS, WSAGetQOSByName, WSCinstallQOSTemplate, WSCRemoveQOSTempilate 


WSAGetQOSByName 


The WSAGetQOSByName function initializes a QOS structure based on a named 
template, or retrieves an enumeration of the available template names: 


ae 


Chapter 15 QOS API Reference 785 


Parameters 


Ss 
[in] Descriptor identifying a socket. 


IDPQOSName 
[in, out] Specifies the QOS template name or supplies a buffer to retrieve an 
enumeration of available template names. 


|pDQOS 
[out] Pointer to the QOS structure to be filled. The ProviderSpecific buffer member of 
the QOS structure must be initialized before calling the WSAGetQOSByName 
function. 


Return Values 


lf WSAGetQOSByName succeeds, the return value is TRUE. If the function fails, the 
return value is FALSE. For extended error information, call WSAGetLastError. 


The algorithm that WSAGetQOSByName applies in its search for a template’s name 
match is: 


e The socket’s service provider checks for a provider- -specific template—a template 
installed specifically for the socket’s service provider—with a name that matches the 
service provider’s name. 


e lf that fails, the service provider checks i its internal table of QOS templates (if it has 
such a table). 7 


e lf that fails, the service provider checks for a list of global QOS templates. 


e If any of the preceding steps succeeds, the service provider can modify the QOS 
template before returning it to Windows Sockets. Otherwise, WSAGetQOSByName 
returns FALSE, and WSAGetLastError returns WSA_NODATA to indicate an 
invalid name. | 


Remarks 

Applications can use WSAGetQOSByName to initialize a QOS structure with a 

_ prescribed set of known values appropriate for a particular service class or media type. 
These known values are stored in a template, and the template is referenced by a well- 

known name. For example, if the service provider's DLL is named Ipphone.dll, the | 

template can be referenced by the name IPPHONE. Applications can retrieve these 

values by setting the buf member of WSABUF, indicated by /pQOSName, to point to a 

string of nonzero length specifying a template name. When doing so, joOQOSName is an 

[in] parameter only, and results are returned through /pQOS. | 


This function can also be used to retrieve an enumeration of available template names. 
This is done by setting the buf member of WSABUF, indicated by |pQOSName, to a 
zero-length, null-terminated string. The buffer indicated by buf is then overwritten with a 
sequence of as many null-terminated template names as are available—up to the 
number of bytes available in buf, as provided by the len member of WSABUF. | 
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The list of names itself is terminated by a zero-length name. When 


WSAGetQOSByName is used to retrieve template names, the /oOQOS parameter is 
ignored. 


If two templates have the same name, with one template being specific to the service 
provider and the other being global, they will appear in the list only once. 


Error Codes 
Error Code Meaning 


WSANOTINITIALIZED A successful call to WSAStartup must occur before using 
this function. 


WSAENETDOWN The network subsystem has failed. 

WSAENOTSOCK The descriptor is not a socket. 

WSAEFAULT | The IpQOSName or |pQOS parameter is not a valid part of 
the user address space. 

WSAENOBUFS The buffer length for /o>QOS is too small. 

WSA_NODATA The specified QOS template name is invalid. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Winsock2.h. 

Library: Use Ws2_32.lib. 


QOS, WSAAccept, WSABUF, WSAConnect, WSAlocti, WSAStartup 


WSClinstallQOSTemplate 


The WSClinstallQOSTemplate function installs a QOS template, based on a QOS 


name. This QOS structure (and thus its QOS settings) can be retrieved by calling the 
WSPGetQOSByName function and passing in its associated QOS name. Note that the 
caller of this function must have administrative rights. 
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Parameters 


loProviderld 
[in] Pointer to a provider-selected globally unique identifier (GUID). 


IpDQOSName 
[in] Specifies the QOS template name. 


IpPQOS 
[in] Pointer to a QOS structure. 


Return Values 
lf WSCInstallQ@OSTemplate succeeds, the return value is TRUE. If the function fails, the 
return value is FALSE. For extended error information, call WSAGetLastError. 


Remarks 

The WSCinstallQOSTemplate function installs a QOS-named template containing the 

_ specified and subsequently associated QOS structure, or replaces settings of an existing 
template. Values are stored in nonvolatile storage, so subsequent calls to 

WSAGetQOSByName, passing the same [pPQOSName, return the QOS structure. If 

IpProviderld is set to NULL, the installed QOS-named template applies across all service 

providers; otherwise the QOS-named template applies only to the provider indicated by 

the /pProviderld parameter. | 


_ Windows Sockets 2 includes a base set of QOS templates. You can override and 
replace any of these QOS templates or change an existing QOS template by simply 
installing a new template with the existing name. You do not need to delete an existing 
template before replacing or modifying it. You cannot delete the base set of QOS-named 
templates included in Windows Sockets 2. However, you can delete templates added 

_ subsequently, perhaps by other service providers. 


The IpQOS parameter, which points to a QOS structure, can include a ProviderSpecific 
buffer that will be stored with the basic QOS structure and returned in subsequent 
WSAGetQOSByName calls. 


You can provide the ProviderSpecific buffer—even if joProviderld is set to NULL—to 
— install global name templates that include provider-specific information. Note that this 
practice may lead the service provider to ignore the ProviderSpecific buffer if the 
service provider does not recognize its contents. The recommended use of 
WSClinstallQOSTemplate is to include a ProviderSpecific buffer only if the named 

~ template is being installed on a particular service provider, as yapiemenee when 
a aalih is not NULL. 
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Error Codes 
Error Code Meaning 


WSAEINVAL The specified QOS template name or provider identifier is invalid, or 
the contents of the template structure is invalid or incomplete. 


WSEFAULT One or more of the parameters is not a valid part of the user address 
space. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qosname.h. 

Library: Use Qosname.lib. 


QOS, WPUGetQOSTemplate, WSAGetQOSByName, WSCRemoveQOSTemplate 


WSCRemoveQOS Template 


The WSCRemoveQOSTemplate function removes a QOS template. Note that the caller 
of this function must have administrative rights. 


arameters 


loProviderld | 
[in] Pointer to a provider-selected globally unique identifier (GUID). 


IpDQOSName 
[in] Specifies the QOS template name. 


Return Values 


lf WSCRemoveQOSTemplate succeeds, the return value is TRUE. If the function fails, 
the return value is FALSE. For extended error information, call WSAGetLastError. 


Remarks 


The WSCRemoveQOSTemplate function deletes a QOS template previously installed 
with WSClinstallQOSTemplate. If joProviderld is NULL, WSCRemoveQOSTemplate 
attempts to find and delete a QOS template from the global list of QOS names. 
Otherwise, WSGCRemoveQOSTemplate attempts to find and delete a QOS template 
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specific to the service provider associated with /oProviderld. You cannot delete the base 


set of QOS names included with Windows Sockets 2. The WSAEINVAL error code will 
be returned if such an attempt is made. 


Error Codes 

Error Code | Meaning 

WSAEINVAL The specified QOS template name is invalid. 
WSA_NODATA The specified QOS template could not be found. 
WSEFAULT One or more of the parameters is not a valid part of the user 


address space. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qosname.h. 

Library: Use Qosname.lib. 


WPUGetQOSTemplate, WSAGetQOSByName, WSCinstallQOSTemplate 


WSPGetQOSByName 


The QOS WSPGetQOSByName function initializes a QOS structure based on. a named 
template, or retrieves an enumeration of the available template names. 


Parameters 
S : 
in] Descriptor identifying a socket. 
iIpPQOSName 
in, out] Specifies the QOS template name or supplies a buffer to retrieve an 
enumeration of available template names. 
IpPQOS ue 
out] Pointer to the QOS structure to be filled. 
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lpErrno 
[out] Pointer to the error code. 


Return Values 


if WSPGetQOSByName succeeds, the return value is TRUE. If the function fails, the 
return value is FALSE. Error information is available in /pErrno. 


The algorithm that WSPGetQOSByName ee in its search for a template’s name 
match is: 


e The service provider checks for a provider-specific template by calling 
WPUGetQOSTemplate, using the service provider's globally eel identifier (GUID) 
and QOS name as search criteria. 


e If that fails, the service provider checks its internal table of QOS templates (if it has 
such a table). 


e lf that fails, the service provider calls WPUGetQOSTemplate again, using the same 
QOS name, but using NULL for the GUID to facilitate a query of the global list of QOS 
names. 


e If any of the preceding steps succeeds, the service provider can modify the QOS 
template before returning it to Windows Sockets. Otherwise, WSPGetQOSByName 
returns FALSE, and /pErrno is set to WSA_NODATA. 


Remarks 


Applications can use this function to initialize a QOS structure with a prescribed set of 
known values appropriate for a particular service class or media type. These known 
values are stored in a template, and the template is referenced by a well-known name. 
Applications can retrieve these values by setting the buf member of WSABUF, indicated 
by |[pQOSName, to point to a string of nonzero length specifying a template name. When 
doing so, /joOQOSName is an [in] parameter only, and results are returned 

through /pQOS. | 


This function can also be used to retrieve an enumeration of available template names. 
This is done by setting the buf member of WSABUF, indicated by /pDQOSName, to a 
zero-length, null-terminated Unicode string. The buffer indicated by buf is then 
overwritten with a sequence of as many null-terminated Unicode template names as are 
available—up to the number of bytes available in buf, as provided by the len member of 
WSABUF. The list of names itself is terminated by a zero-length Unicode name string. 
When WSPGetQOSByName is used to retrieve aernpiete names, the IpQOs pelametey : 
is ignored. 


Error Codes 
Error Code Meaning 
WSAENETDOWN The network subsystem has failed. 


WSAENOTSOCK The descriptor is not a socket. 
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Error Code Meaning 
WSAEFAULT The IpQOSName or /pQOS parameter is not a valid part of 
the user address space. 
WSAENOBUFS The buffer length for /oQOS is too small. 
~ WSA_NODATA The specified QOS template name is invalid. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Ws2spi.h. 


QOS, WPUGetQOSTemplate, WSABUF, WSClnstall@OSTemplate, 
WSCRemoveQOSTemplate 


QOS Structures 


This section describes the following Quality of Service structures: 
e FLOWSPEC 
e QOS 


FLOWSPEC 


The FLOWSPEC structure provides QOS parameters to the RSVP SP. This allows 
QOS-aware applications to invoke, modify, or remove QOS settings for a given flow. 


Some members of FLOWSPEC can be set to default values. See Remarks for m ore 
information. — : 7 | , 
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Members 


TokenRate 
Specifies the permitted rate at which data can be transmitted over the life of the flow. 
TokenRate is similar to other token bucket models seen in such WAN technologies 
as Frame Relay, in which the token is analogous to a credit. If such tokens are not 
used immediately, they accrue to allow data transmission up to a certain periodic limit 
(PeakBandwidth, in the case of Windows 2000 QOS). Accrual of credits is limited, 
however, to a specified amount (TokenBucketSize). Limiting total credits (tokens) 
avoids situations where, for example, flows that are inactive for some time flood the 
available bandwidth with their large amount of accrued tokens. Because flows may 
accrue transmission credits over time (at their TokenRate value) only up to the 
maximum of their TokenBucketSize, and because they are limited in burst 
transmissions to their PeakBandwidth, traffic control and network-device resource 
integrity are maintained. Traffic control is maintained because flows cannot send too 
much data at once, and network-device resource integrity is maintained because such 
devices are spared from high traffic bursts. 


With this model, applications can transmit data only when sufficient credits are 
available. If sufficient credits are not available, the application must either wait or 
discard the traffic (based on the value of QOS_OBJECT_SD_MODE). Therefore it is 
important that applications base their TokenRate requests on reasonable 
expectations for transmission requirements. For example, in video applications, 
TokenRate is typically set to the average bit rate from peak to peak. 


lf TokenRate is set to QOS_NOT_SPECIFIED on the receiver only, the maximum 
transmission unit (MTU) is used for TokenRate, and limits on the transmission rate 
(the token bucket model) will not be put into effect. TokenRate is expressed in bytes 
per second. 


TokenRate cannot be set to zero. TokenRate cannot be set as a default (that is, set 
to QOS_NOT_SPECIFIED) in a sending FLOWSPEC. , 


TokenBucketSize | 
The maximum amount of credits a given direction of a flow can accrue, regardless of 
time. In video applications, TokenBucketSize will likely be the largest average frame 
size. In constant rate applications, TokenBucketSize should be set to allow for small 
variations. TokenBucketSize is expressed in bytes. 


PeakBandwidth 
The upper limit on time-based transmission permission for a given flow, sometimes 
considered a burst limit. PeakBandwidth restricts flows that may have accrued a 
significant amount of transmission credits, or tokens from overburdening network 
resources with one-time or cyclical data bursts, by enforcing a per-second data 
transmission ceiling. Some intermediate systems can take advantage of this 
information, resulting in more efficient resource allocation. PeakBandwidth is 
expressed in bytes per second. | 


Value 
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Latency 
Maximum acceptable delay between transmission of a bit by the sender and its 
receipt by one or more intended receivers. The precise interpretation of this number 
depends on the level of guarantee specified in the QOS request. Latency is 
expressed in microseconds. 


DelayVariation 
Difference between the maximum and minimum possible delay a packet will 
experience. Applications use DelayVariation to determine the amount of buffer space 
needed at the receiving end of the flow. This buffer space information can be used to 
restore the original data transmission pattern. DelayVariation is oni in 
microseconds. 


ServiceType 
Specifies the level of service to negotiate for the flow. This member can be one of the 
following defined service types: , 


Meaning 


SERVICETYPE_NOTRAFFIC Indicates that no traffic will be transmitted in the 


specified direction. On duplex-capable media, this 
value signals underlying software to set up 
unidirectional connections only. This service type | 
is not valid for the TC API. 


SERVICETYPE_BESTEFFORT ~ | Results in no action taken by the RSVP SP. Traffic 


control does create a BESTEFFORT flow, 
however, and traffic on the flow will be handled by 
traffic control similarly to other BESTEFFORT 
traffic. 


SERVICETYPE_CONTROLLEDLOAD Provides an end-to-end QOS that closely 


approximates transmission quality provided by 
best-effort service, as expected under unloaded 
conditions from the associated network 
components along the data path. 


_. Applications that use | 
SERVICETYPE_CONTROLLEDLOAD may 
therefore assume the following: 


e The network will deliver a very high percentage 
of transmitted packets to its intended receivers. In 
other words, packet loss will closely approximate 
the basic packet error rate of the transmission 
medium. 

e Transmission delay for a very high serena 
of the delivered packets will not greatly exceed the 
minimum transit delay experienced by any 
successfully delivered packet. 


(continued) 
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(continued) 


Value 


SERVICETYPE_GUARANTEED 


SERVICETYPE_QUALITATIVE 


SERVICETYPE_NETWORKCONTROL 


SERVICETYPE_GENERAL_INFORMATION 


SERVICETYPE_NOCHANGE 


SERVICE_NO_TRAFFIC_CONTROL 


SERVICE_NO_QOS_SIGNALING 


Meaning 


Guarantees that datagrams will arrive within the 
guaranteed delivery time and will not be discarded 
due to queue overflows, provided the flow’s traffic 
stays within its specified traffic parameters. This 
service is intended for applications that need a firm 
guarantee that a datagram will arrive no later than 


-acertain time after it was transmitted by its source. 


Indicates that the application requires better than 
BESTEFFORT transmission, but cannot quantify 
its transmission requirements. Applications that 
use SERVICETYPE_QUALITATIVE can supply an 
application ID policy object. The application ID 
policy object enables policy servers on the network 
to identify the application, and accordingly, assign 
an appropriate QOS to the request. For more 
information on application ID, consult the IETF 
Internet Draft draft-ietf-rap-rsvp-appid-00.txt, or the 
Microsoft white paper on Application ID. Traffic 
control treats flows of this type with the same 
priority as BESTEFFORT traffic on the local 
computer. However, application programmers can 
get boosted priority for such flows by modifying the 
Layer 2 settings on the associated flow using the 
QOS_OBJECT_TRAFFIC_CLASS QOS object. 


Used only for transmission of control packets 
(such as RSVP signaling messages). This 
ServiceType has the highest priority. 


Specifies that all service types are supported for a 
flow. Can be used on sender side only. 


Indicates that the QOS in the transmission using 
this ServiceType value is not changed. 
SERVICETYPE_NOCHANGE can be used when 
requesting a change in the QOS for one direction 
only, or when requesting a change only within the 
ProviderSpecific parameters of a QOS > 
specification, and not in the SendingFlowspec or 
ReceivingFlowspec. 


Indicates that traffic control should not be invoked 
in the specified direction. 


Suppresses RSVP signaling in the specified 
direction. : 
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The following list identifies the relative priority of ServiceType settings: 


SERVICETYPE_NETWORKCONTROL 
SERVICETYPE_GUARANTEED 
SERVICETYPE_CONTROLLED_LOAD 
SERVICETYPE_BESTEFFORT, SERVICETYPE_QUALITATIVE 
Non-conforming traffic 


For a simple example, if a given network device were resource-bounded and had to 
choose among transmitting a packet from one of the above ServiceType settings, it 
would first send a packet of SERVICETYPE_NETWORKCONTROL, and if there were 
no packets of that ServiceType requiring transmission it would send a packet of 
ServiceType SERVICETYPE_GUARANTEED, and so on. 


MaxSduSize 
Specifies the maximum packet size permitted or used in the traffic flow. This member 
is expressed in bytes. 7 


MinimumPolicedSize | 
Specifies the minimum packet size for which the requested QOS will be provided. 
Packets smaller than this size are treated by traffic control as MinimumPolicedSize. 
The MinimumPolicedSize member is expressed in bytes. When using the 
FLOWSPEC structure in association with RSVP, the value of MinimumPolicedSize | 
cannot be zero; however, if you are using the FLOWSPEC structure specifically with 
the TC API, you can set MinimumPolicedSize to zero. | 


Remarks 

Many members of the FLOWSPEC structure can be set to default values by setting the 
member to QOS_NOT_SPECIFIED. Note that the members that can be set to default 
values differ depending on whether the FLOWSPEC is a receiving FLOWSPEC ora 
sending FLOWSPEC. 


There are a handful of considerations you should keep in mind when using FLOWSPEC 
with traffic control: 


e TokenRate can be QOS_NOT_SPECIFIED for 
SERVICETYPE_NETWORKCONTROL, SERVICETYPE _QUALITATIVE, and 
SERVICETYPE_BESTEFFORT. TokenRate must be valid for all other ServiceType 
values. 


e If PeakBandwidth is specified, it must be greater than or equal to TokenRate. 
Many settings can be defaulted in a receiving FLOWSPEC except ServiceType, with 
the following considerations: 


e For a Controlled Load Service receiver, the default values are derived from the sender 
TSPEC. 


e Fora Guaranteed aides receiver, ServiceType and TokenRate must be specified. 
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The following list specifies the values that are applied when a receiving FLOWSPEC 
sets the corresponding values to default: 


TokenRate 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the TokenRate parameter in the senders FLOWSPEC. 
TokenBucketSize 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the TokenBucketSize parameter in the senders FLOWSPEC. 
PeakBandwidth | 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the PeakBandwiath parameter in the sender's FLOWSPEC. 
Latency 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the Latency parameter in the sender's FLOWSPEC. 
Service Type | 
Must be specified. 
DelayVariation 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the DelayVariation parameier in the sender’s FLOWSPEC. 
MaxSduSize 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the MaxSduSize parameter in the sender's FLOWSPEC. 
MinimumPolicedSize 
Set to QOS_NOT_SPECIFIED when defaulted in a receiving FLOWSPEC. The value 
is set to the MinimumPolicedSize parameter in the sender’s nee 


When the value of the ServiceType is set to SERVICETYPE_GUARANTEED, the 
following also applies: 


e The RATE value in RSPEC is set to the value of TokenRate. 


e The DELAYSLACKTERM value in RSPEC is set to DelayVariation, which is set to 
zero if DelayVariation is set to QOS_NOT_SPECIFIED. 
e For receivers requesting SERVICET YPE_GUARANTEED, the receiving TokenRate 


must be specified. This contrasts with a SERVICETYPE_CONTROLLEDLOAD 
receiver, for which TokenRate may be set to QOS_NOT_SPECIFIED. 


_Inasending FLOWSPEC, everything can be defaulted except ServiceType and 


TokenRate. The following list specifies the values that are applied when a sending 
FLOWSPEC sets the corresponding values to default: 


TokenRate 
Must be specified. 


TokenBucketSize | | 
Set to 1500 bytes when defaulted in a receiving FLOWSPEC. 


Qos 
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PeakBandwidth 
Set to the local link speed, if known, sitierwise set to POSITIVE_INIFINITY when 
defaulted ina erewina FLOWSPEC. 


Latency 
Set to 0 msec when defaulted in a receiving FLOWSPEC. 


DelayVariation © 
Set to 0 msec when defaulted in a aeavae FLOWSPEC. 


ServiceType 
Must be specified. 


MaxSduSize 
Set to 1500 bytes when defaulted in a receiving FLOWSPEC. 


MinimumPolicedSize 
Set to 128 bytes when defaulted in a receiving FLOWSPEC. 


Notes for Traffic Control The following ServiceTypes are invalid when specifically 
working with Traffic Control. If you are unsure whether you are working directly with 
Traffic Control (and thereby need to be concerned about whether the following 
ServiceTypes are applicable in your situation), you probably are not: 


SERVICETYPE_NOTRAFFIC 
SERVICETYPE_NETWORK_UNAVAILABLE 
SERVICETYPE_GENERAL_INFORMATION 
SERVICETYPE_NOCHANGE 
SERVICE_NO_TRAFFIC_CONTROL 


~SERVICE_NO_QOS_SIGNALING 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qos.h. 


QOS 
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The QOS structure provides the means by which QOS-enabled applications can specify 


quality of service Palamelels for sent and received traffic on a particular flow. 
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Members 


SendingFlowspec | 
Specifies QOS parameters for the sending direction of a particular flow. 
SendingFlowspec is sent in the form of a FLOWSPEC structure. 


ReceivingFlowspec 
Specifies QOS parameters for the receiving direction of a particular flow. 
ReceivingFlowspec is sent in the form of a FLOWSPEC structure. 


ProviderSpecific 
| Pointer to a structure of tyoe WSABUF that can provide additional provider-specific 
QOS parameters to the RSVP SP for a given flow. 


Remarks - 


Most applications can fulfill their quality of service requirements without using the 
ProviderSpecific buffer. However, if the application must provide information not 
available with standard Windows 2000 QOS parameters, the ProviderSpecific buffer 
allows the application to provide additional parameters for RSVP and/or traffic control. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Winsock2.h. 


FLOWSPEC, ProviderSpecific 


QOS Objects ae 


Applications that require specific or granular quality of service control, beyond what is 
available in the QOS API, can use QOS objects. QOS objects implement functionality 
specific to the Microsoft® Windows 2000® operating system, such as traffic control- 
related objects, as well as industry-wide functionality such as RSVP-related objects. 
QOS objects are implemented through the ProviderSpecific buffer in the FLOWSPEC 
structure, which is a member of the QOS structure. 
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QOS objects follow a stringent structure. QOS objects always include an information 
header that specifies the type and length of the rac object to which it is attached, 
followed by the object itself. 


This section describes the following: 


e The ProviderSpecific Buffer 

e QOS_OBJECT_HDR 

° QOS_OBJECT_DESTADDR 

¢ QOS_OBJECT_SD_MODE 

e QOS_OBJECT_SHAPING_RATE 
¢ RSVP_ADSPEC | | 
e RSVP_RESERVE_INFO 

e RSVP_STATUS_INFO 


The ProviderSpecific Buffer 


The ProviderSpecific buffer provides applications that have special QOS needs with a 
mechanism that enables fine-grained tuning of required QOS parameters. The 
ProviderSpecific buffer is of type WSABUF as defined by Windows Sockets 2 and is a 
member of the QOS structure. 


The standard mechanisms by which Windows 2000 Qos enables service quality 
provisioning fulfills QOS requirements for the majority of applications. In some situations, 
however, service quality parameters not available with standard QOS mechanisms may — 
need to be implemented. The ProviderSpecific buffer interface is provided for those 
situations. : 


The ProviderSpecific buffer specifically includes a length field and a pointer to a buffer, 
which may contain one or more QOS objects. The format of each object is as follows: 


-. @ Each object includes a type field, which specifically identifies the object, followed by: 


_ @ A length field, which contains the length of the object inclusive of the header, 
followed by: 3 : 


e The object data itself. — 


ag QOS Objects for more information. 


QOos_ OBJECT_ HDR - 


‘The Qos object Qos_ OBJECT. HDR is attached to each QOS: object, It specifies the. 
object type and its length. 
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Members 


ObjectType 
Specifies the type of object to which QOS_OBJECT_HDR is attached. 


ObjectLength 
Specifies the length of the attached object, inclusive of QOS_OBJECT_HDR. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Qos.h. 


QOS_OBJECT_DESTADDR 


The QOS object QOS_OBJECT_DESTADDR is used during a call to the 
WSAloctl(SIO_SET_QOS) function in order to avoid issuing a connect function call for 


a sending socket. 


sponeennseenneennagete 


Members 


ObjectHdr 
The QOS object QOS_OBJECT_HDR. The object type for this QOS object should be 


QOS_OBJECT_DESTADDR. 


SocketAddress 
Address of the destination socket. 


SocketAddressLength 
Length of the SocketAddress structure. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Qossp.h. 
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QOS_OBJECT_SD_MODE 


The QOS object QOS. OBJECT_SD_ MODE defines the behavior of the traffic control— 
packet shaper component. 


Members 
ObjectHdr 


The QOS object QOS_OBJECT_HDR. The object type for this Qos object should be 
QOS_OBJECT_SD_MODE. 


ShapeDiscardMode 
Specifies the requested behavior of the packet shaper. Note that there are elements 
of packet handling within these predefined behaviors that depend on the flow settings © 
specified within FLOWSPEC. 


Value 
TC_NONCONF_BORROW 


TC_NONCONF_SHAPE 


TC_NONCONF_DISCARD 


Meaning 


Instructs the packet shaper to borrow remaining available resources 
after all higher priority flows have been serviced. If the TokenRate 
member of FLOWSPEC is specified for this flow, packets that 
exceed the value of TokenRate will have their priority demoted to 
less than SERVICETYPE_BESTEFFORT, as defined in the 
ServiceType member of the FLOWSPEC structure. 


Instructs the packet shaper to retain packets until network 
resources are available to the flow in sufficient quantity to make 
such packets conforming. (For example, a 100K packet will be 
retained in the packet shaper until 100K worth of credit is accrued 
for the flow, allowing the packet to be transmitted as conforming). 
Note that TokenRate must be specified if using 
TC_NONCONF_SHAPE. 


Instructs the packet shaper to discard all nonconforming packets. 
TC_NONCONF_DISCARD should be used with care. 


Windows NT/2000: Requires Windows 2000. 


Windows 95/98: Unsupported. 
Header: Declared in Qos.h. 
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QOS_OBJECT_SHAPING_RATE 


The QOS object QOS_OBJECT_SHAPING_RATE specifies the type of shaping 
behavior to be applied to a given flow. 


Members 


ObjectHdr 
The QOS object QOS_OBJECT_HDR. The object type for this QOS object should be 
QOS_OBJECT_SHAPING_RATE. 


ShapingRate 
Value that corresponds to the required shaping rate, as follows: 
TC_NONCONF_BORROW 
The flow receives resources that remain after all higher priority flows have been 


serviced. If a TokenRate is specified, packets may be non-conforming and are 
demoted to less than best-effort priority. 


TC_NONCONF_SHAPE 
TokenRate must be specified. Nonconforming packets are retained in the packet 
shaper until they become conforming. 


TC_NONCONF_DISCARD 
TokenRate must be specified. Nonconforming packets are discarded. 


TC_NONCONF_BORROW_PLUS . 
Similar to TC_NONCONF_BORROW, but no packets will be marked as non- 


conforming. Note that the setting ShapingRate to value cannot be accomplished 
with the QOS API; it must be done through the traffic contro! API (the TC API). 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Qos.h. 


RSVP_ADSPEC 


The QOS object RSVP_ADSPEC provides a means by which information describing 
network devices along the data path between sender and receiver, pertaining to RSVP 
functionality and available services, is provided or retrieved. 
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Members 


ObjectHdr 
The QOS object QOS_OBJECT_HDR. 


GeneralParams 


An AD_GENERAL_PARAMS structure that provides general characterization 
parameters for the flow. Information includes RSVP-enabled hop count, bandwidth 
and latency estimates, and the path’s MTU. 
NumberOfServices 
Provides a count of the number of services available. (See the following member for 
more information.) 


Services 


A CONTROL_SERVICE array, its element count based on NumberOfServices, 


which provides information about the services available along the data path between - 
the sender and receiver of a given flow. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qossp.h. 


RSVP_RESERVE_INFO 


The QOS object RSVP_RESERVE_INFO, through the ProviderSpecific buffer, allows 
RSVP behavior for a given flow to be specified or modified at a granular level, and allows 
default RSVP style settings for a flow to be overridden. Although | Ps 
RSVP_RESERVE_INFO is technically a structure, its use within Windows 2000 QOS 


technology—and especially its required inclusion of the QOS_OBJECT_HDR as its first 
member—define it as a QOS object. 


Pe 


(continued) 
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(continued) 


Members 
ObjectHdr 


The QOS object @OS_OBJECT_HDR. 


Style 


Specifies the RSVP reservation style for a given flow, and can be used to replace 
default reservation styles placed on a particular type of flow. More information about 
RSVP reservation styles, and the default settings for certain QOS-enabled socket 
sessions, can be found under Network-Driven QOS Components. This member can 
be one of the following values. 


~ Value 


Meaning 


RSVP_WILDCARD_SYLE 


RSVP_FIXED_FILTER_STYLE 


RSVP_SHARED_EXPLICIT_STYLE 


Implements the WF RSVP reservation style. 
RSVP_WILDCARD_STYLE is the default value for 
multicast receivers and UDP unicast receivers. Specifying 
RSVP_WILDCARD_STYLE through 
RSVP_RESERVE_INFO is useful for overriding the 
default value (RSVP_FIXED_FILTER_STYLE) applied to 
connected unicast receivers. 


Implements the Fixed Filter (FF) RSVP reservation style. 
RSVP_FIXED_FILTER_STYLE is useful for overriding the 
default style for multicast receivers or unconnected UDP 
unicast receivers (RSVP_WILDCARD_STYLE). It may 
also be used to generate multiple - 
RSVP_FIXED_FILTER_STLYE reservations in instances 
where only a single RSVP_FIXED_FILTER_STYLE 
reservation will be generated by default, such as with 
connected unicast receivers. | 


Implements the Shared Explicit (SE) RSVP reservation 
style. 
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Note It is important to note that the number of senders included in any individual 
RSVP_SHARED_EXPLICIT_STYLE reservation must be less than one hundred 
senders. If more than one hundred senders attempt to connect to an 
RSVP_SHARED_EXPLICIT_STYLE reservation, the one-hundredth (and above) 
attempt fails without notice. 


ConfirmRequest 
Can be used by a receiving application to request notification of its reservation 
request by setting ConfirmRequest to a nonzero value. Such notification is achieved 
when RSVP-aware devices in the data path between sender and receiver (or vice- 
versa) transmit an RESV CONFIRMATION message toward the requesting node. 
Note that an RSVP node is not required to automatically generate RESV 
CONFIRMATION messages. 


NumPolicyElement 
Specifies the number of policy elements. 


PolicyElementList 


Pointer to the set of policy elements. Optional policy information, as provided in an 
RSVP_POLICY structure. 


NumFlowDesc 
Specifies the FLOWDESCRIPTOR count. 


FlowDescList 
Pointer to the list of FLOWDESCRIPTORs. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qossp.h. 


RSVP_STATUS_INFO 


The QOS object RSVP_STATUS_INFO provides information regarding the status of 
RSVP for a given flow, including event notifications associated with monitoring FD_QOS 
events, as well as error information. RSVP_STATUS_INFO is useful for storing RSVP- 
specific status and error information. | 


(continued) 
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(continued) 


Members 


ObjectHdr | 
The QOS object QOS_OBJECT_HDR. 


StatusCode 
Status information. See Winsock2.h for more information. 


ExtendedStatus1 
Mechanism for storing or returning provider-specific status information. The 
ExtendedStatus1 parameter is used for storing a higher-level, or generalized error 
code, and is augmented by finer-grained error information provided in 
ExtendedStatus2. 


ExtendedStatus2 | 
Additional mechanism for storing or returning provider-specific status information. 
Provides finer-grained error information compared to the generalized error information 
provided in ExtendedStatus1. 


Remarks 


When applications register their interest in FD_QOS events (see QOS Events), event 
and error information is associated with the event in the form of the QOS structure that is 
associated with the event. For more detailed information associated with that event, 
applications can investigate the RSVP_STATUS_INFO object that is provided in the 
ProviderSpecific buffer of the event-associated QOS structure. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Requires Windows 98. 
Header: Declared in Qossp.h. 
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CHAPTER 16 


Traffic Control API Reference 


Traffic Control Functions 


TcAddFilter 


The TcAddFilter function associates a new filter with an existing flow that allows 
packets matching the filter to be directed to the associated flow. 


Filters include a pattern and a mask. The pattern specifies particular parameter values, 
while the mask specifies which parameters and parameter subfields apply to a given 
filter. When a pattern and mask combination is applied to a set of packets, matching 
packets are directed to the flow to which the corresponding filter is associated. 


Traffic control returns a handle to the newly added filter, in the pFilterHandle parameter, 
by which clients can refer to the added filter. Pending flows, such as those processing a 
TcAddFlow or TcModifyFlow request for which a callback routine has not been _ 
completed, cannot have filters associated to them; only flows that have been compiled: 
and are stable can apply associated filters. 


The relationship between filters and flows is many to one. . Multiple filters can be applied - 
to a single flow; however, a filter can only apply to one flow. For example, flow A can 
have filters X, Y and Z applied to it, but as long as flow A is active, filters X, Y and Z 
cannot apply to any other flows. 


Parameters 


FlowHandle 
[in] Handle for the flow, as received from a previous call to ‘the e TeAddFlow function. 


pGenericFilter 
[in] Pointer to a description of the filter to be installed. 


pFilterHandle os | 
[out] Pointer to a buffer where traffic control returns the filter handle. This filter ees 
is used by the client in subsequent calts to refer to the added filter. 
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Return Values 
Error codes 


NO_ERROR 
ERROR_INVALID_HANDLE 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_PARAMETER 
ERROR_INVALID_ADDRESS_TYPE 
ERROR_DUPLICATE_FILTER 


ERROR_FILTER_CONFLICT 


ERROR_NOT READY 


Remarks 


Description 


The function executed without errors. 

The flow handle is invalid. 

The system is out of memory. 

A parameter is invalid. 

An invalid address type has been provided. 


An identical filter exists on a flow on this 
interface. 


A conflicting filter exists on a flow on this 
interface. 


The flow is either being installed, modified, or 
deleted, and is not in a state that accepts 
filters. 


Filters can be of different types. They are typically used to filter packets belonging to 


different network layers. Filter types installed on an interface generally correspond to the 
address types of the network layer addresses associated with the interface. The address 
type should be specified in the filter structure. 


Filters may be rejected for various reasons, including possible conflicts with the 
requested filter and those filters already associated with the flow. Error codes specific to 
traffic control are provided to help the user diagnose the reason behind a rejection to the 
TcAddFilter function. 


Note Use of the TcAddFilter function requires administrative privilege. 


_ Windows NT/2000: Requires Windows 2000. 
‘Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcAddFlow 
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TcAddFlow 


The TcAddFlow function adds a new flow on the specified interface. Note that the 
successful addition of a flow does not necessarily indicate a change in the way traffic is 
handled; traffic handling changes are effected by attaching a filter to the added flow, 
using the TcAddFilter function. 


Traffic control clients that have registered an AddFlowComplete handler (a mechanism 
for allowing traffic control to call the Cl[AddFlowComplete callback function in order to 
alert clients of completed flow additions) can expect a return value of 
ERROR_SIGNAL_PENDING. For more information, see Traffic Control Objects. 


Parameters 


lfcHandle 
[in] Handle associated with the interface on which the flow is to be added. This handle 
is obtained by a previous call to the TcOpeninterface function. 


CIFlowCix — | 
[in] Client provided—flow context handle. Used subsequently by traffic control when 
referring to the added flow. | | 


Flags 
[in] Reserved for future use. Must be set to zero. 


pGenericFlow 
[in] Pointer to a description of the flow being installed. 


pFlowHandle 
[out] Pointer to a location into which traffic control will return the flow handle. This flow 
handle should be used in subsequent calls to traffic control to refer to the installed 
flow. | 


Return Values 


There are many reasons why a request to add a flow might be rejected. Error codes 
returned by traffic control from calls to TCAddFlow are provided to aid in determining the 
reason for rejection. For more information on the validation rules applied to flow 
requests, see traffic control. 
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Error codes 


NO_ERROR 
ERROR_SIGNAL_PENDING 


~ ERROR_INVALID_HANDLE 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_PARAMETER 
ERROR_INVALID_SERVICE_TYPE 


ERROR_INVALID_TOKEN_RATE 


ERROR_INVALID_PEAK_RATE 
ERROR_INVALID_SD_MODE 
ERROR_INVALID_QOS_PRIORITY 
ERROR_INVALID_TRAFFIC_CLASS 
ERROR_NO_SYSTEM_RESOURCES 


ERROR_TC_OBJECT_LENGTH_ 
INVALID 


ERROR_INVALID_DIFFSERV_FLOW 


ERROR_DS_MAPPING_EXISTS 


ERROR_INVALID_SHAPE_RATE 


-ERROR_INVALID_DS_CLASS 
ERROR_NETWORK_UNREACHABLE 


Description 


The function executed without errors. 
The function is being executed 
asynchronously; the client will be called 
back through the client-exposed 
ClAddFlowComplete function when the 
flow has been added or when the process 
has been completed. 

The interface handle is invalid. 

The system is out of memory. 

A parameter is invalid. 

An unspecified or bad INTSERV service 
type has been provided. 

An unspecified or bad TOKENRATE value 
has been provided. 

The PEAKBANDWIDTH value is invalid. 
The SHAPEDISCARDMODE is invalid. 
The priority value is invalid. 

The traffic class value is invalid. 

There are not enough resources to 
accommodate the requested flow. 

Bad length specified for the TC objects. 


Applies to Diffserv flows. Indicates that the 
QOS_OBJECT_DIFFSERV object was 
passed with an invalid parameter. 

Applies to Diffserv flows. Indicates that the 
QOS_DIFFSERV_RULE specified in 
TC_GEN_FLOW already applies to an 
existing flow on the interface. 

The QOS_OBJECT_SHAPING_RATE 
object was passed with an invalid 
ShapeRate. 


The QOS_OBJECT_DS_CLASS is invalid. 


The network cable is not plugged into the 
adapter. 
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Remarks 


If the TcAddFlow function returns ERROR_SIGNAL_PENDING, the 
ClAddFlowComplete function will be called on a different thread than the thread that 
called the TcAddFlow function. 


Only the addition of a filter will affect traffic control. However, the addition of a flow will 
Cause resources to be committed within traffic control components. This enables traffic 
control to prepare for handling traffic on the added flow. 


Traffic control may delete a flow for various reasons, including the inability to 
accommodate the flow due to bandwidth restrictions, and adjusted policy requirements. 
Clients are notified of deleted flows through the CINotifyHandler callback function, with 
the TC_NOTIFY_FLOW_CLOSE event. 


Note Use of the TcAddFlow function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TeCloseinterface 


The TcCloseintertace function closes an interface previously opened with a call to 
TcOpeninterface. All flows and filters on a particular interface should be closed before 
closing the interface with a call to TcCloselnterface. 


Parameters 


lfcHandle 
[in] Handle associated with the interface to be closed. This handle i is obtained by a 
previous call to the TcOpeninterface function. 


Return Values 

Error code Description 

NO_ERROR | eres The function executed without errors. 
ERROR_INVALID_HANDLE ~ The interface handle is invalid. 


ERROR_TC_ SUPPORTED -OBJECTS_ Not all flows have been deleted for this 
EXIST | . interface. 
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Remarks 


Regardless of whether TcCloselnterface is called, an interface will be closed following a 
TC_NOTIFY_IFC_CLOSE notification event. If the TeCloselnterface function is called 
with the handle of an interface that has already been closed, the handle will be 
invalidated and TcCloselnterface will return ERROR_INVALID_HANDLE. 


Note Use of TcCloselnterface requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcOpeninterface 


TcDeleteFilter | 


The TcDeleteFilter function deletes a filter previously added with the TecAddFilter 
function: 


Parameters 

FilterHandle 
[in] Handle to the filter to be deleted, as received in a previous call to the TcAddFilter 
function. 

Return Values 

Errorcodes ~ Description 

NO_ERROR The function executed without errors. 

ERROR_INVALID_ HANDLE The filter handle is invalid. 


Note Use of the TcDeleteFilter function requires administrative privilege. — 
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Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic. lib. 


TcAddFilter 


TcDeleteFlow 


The TcDeleteFlow function deletes a flow that has been added with the TcAddFlow 
function. Clients should delete all filters associated with a flow before deleting it, 
otherwise, an error will be returned and the function will not delete the flow. 


Traffic control clients that have registered a DeleteFlowComplete handler (a 
mechanism for allowing traffic control to call the CIDeleteFlowComplete callback 


function in order to alert clients of completed flow deletions) can expect a return value of 
ERROR_SIGNAL_PENDING. 


Parameters 
FlowHandle 
[in] Handle for the flow, as received from a previous call to the TcAddFlow function. 


Return Values 

Error codes Description 

NO_ERROR The function executed without errors. 
ERROR_SIGNAL_PENDING The function is being executed 


asynchronously; the client will be called 
back through the client-exposed 
CiDeleteFlowComplete function when the 
flow has been added, or when the process 
has been completed. : 


ERROR_INVALID_HANDLE The flow handle is invalid or NULL. 


ERROR_TC_SUPPORTED_OBJECTS___ At least one filter associated with this flow 
EXIST exists. a 
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Remarks 


If the TcDeleteFlow function returns ERROR_SIGNAL_PENDING, the 
CiDeleteFlowComplete function will be called on a different thread than the thread that 
called the TcDeleteFlow function. 


Note Use of the TcDeleteFlow function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcEnumerateFlows, TcAddFlow, CiDeleteFlowComplete 


TcDeregisterClient 


The TcDeregisterClient function deregisters a client with the Traffic Control Interface 
(TCI). Before deregistering, a client must delete each installed flow and filter with the 
TcDeleteFlow and TcDeleteFilter functions, and close all open interfaces with the 
TcCloselnterface function, respectively. 


Parameters 


ClientHandle | 
[in] Handle assigned to the client through the previous call to the TcRegisterClient 


function. 


Return Values 


Error codes Description 

NO_ERROR The function executed without errors. 

ERROR_INVALID_HANDLE Invalid interface handle, or the handle was 
set to NULL. | 

ERROR_TC_SUPPORTED_OBJECTS_ __Interfaces are still open for this client. all 

EXIST | interfaces must be closed to deregister a 


client. 
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Remarks 


Once a client calls TcDeregisterClient, the only traffic control function the client is 
allowed to call is TcRegisterClient. 


Note Use of the TcDeregisterClient function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcRegisterClient, TcCloselnterface, TcDeleteFlow, TcDeleteFilter 


TcEnumerateFlows 


The TcEnumerateFlows function enumerates installed flows and their associated filters 
on an interface. 


The process of returning flow enumeration often consists of multiple calls to the 
TcEnumerateFlows function. The process of receiving flow information from 
TcEnumerateFlows can be compared to reading through a book in multiple sittings—a 
certain number of pages are read at one time, a bookmark is placed where the reading 
stopped, and reading is resumed from the bookmark until the book is finished. 


The TcEnumerateFlows function fills the Buffer parameter with as many flow 
enumerations as the buffer can hold, then returns a handle in the pEnumToken 
parameter that internally bookmarks where the enumeration stopped. Subsequent calls 
to TcEnumerateFlows must then pass the returned pEnumToken value to instruct traffic 
control where to resume flow enumeration information. When all flows have been 
enumerated, pEnumToken will be NULL. 
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Parameters 

lfcHandle 
[in] Handle associated with the interface on which flows are to be enumerated. This 
handle is obtained by a previous call to the TcOpeninterface function. 


pEnumToken 
[in, out] Pointer to the enumeration token, used internally by traffic control to maintain 
returned flow information state. 


For input of the initial call to TcEnumerateFlows, pbEnumToken should be set to 
NULL. For input on subsequent calls, pEnumToken must be the value returned as the 
pEnumToken OUT parameter from the immediately preceding call to 
TcEnumerateFlows. | 


For output, obEnumToken is the refreshed enumeration token that must be used in the 
following call to TcEnumerateFlows. 


pFlowCount 
[in, out] Pointer to the number of requested or returned flows. For input, this 
parameter designates the number of requested flows or it can be set to (—1) to 
request all flows. For output, pbFlowCount returns the number of flows actually 
returned in Buffer. 

pBufSize 
[in, out] Pointer to the size of the client-provided buffer or the number of bytes used by 
traffic control. For input, points to the size of Buffer, in bytes. For output, points to the 
actual amount of buffer space, in bytes, written or needed with flow enumerations. 

Buffer 
[out] Pointer to the buffer containing flow enumerations. See 
ENUMERATION_BUFFER for more information about flow enumerations. 


Return Values 


Error codes Description 
NO_ERROR _ The function executed without errors. 
ERROR_INVALID_HANDLE Invalid interface handle. — 
ERROR_INVALID_PARAMETER One of the pointers is NULL, or pFlowCount 
or pBufSize are set to zero. 
ERROR_INSUFFICIENT_BUFFER The buffer is too small to store even a 
single flow’s information and attached 
filters. | | , 
ERROR_NOT_ENOUGH_MEMORY The system is out of memory. 
ERROR_INVALID_DATA The enumeration token is no longer valid. 
Remarks 


Do not request zero flows, or pass a buffer with a size equal to zero or pointer toa 
NULL. 
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If an enumeration token pointer has been invalidated by traffic control (due to the 
deletion of a flow), continuing to enumerate flows is not allowed, and the call will return 
ERROR_INVALID_DATA. Under this circumstance, the process of enumeration must 
start over. This circumstance can occur when the next flow to be enumerated is deleted 


while enumeration is in progress. 


To get the total number of flows for a given interface, call TcQuerylnterface and specify 
GUID_QOS_FLOW_COUNT. 


Note Use of the TcEnumerateFlows function requires administrative privilege. 


‘ Ee 
Sor 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic. lib. 


TcOpenintertace, TcQueryinterface 


-TcEnumeratelnterfaces 


The TcEnumerateinterfaces function enumerates all traffic control-enabled network 
interfaces. Clients are notified of interface changes through the CINotifyHandler 


function. 


Parameters 

ClientHandle 
[in] Handle used by traffic control to identify the client. Clients receive handles when 
registering with traffic control through the TcRegisterClient function. 


pBufferSize , 
[in, out] Pointer to a value indicating the size of the buffer. For input, this value is the 


size of the buffer, in bytes, allocated by the caller. For output, this value is the actual 
size of the buffer, in bytes, used or needed by traffic control. A value of zero on output 
indicated that no traffic control interfaces are available, indicating that the QOS 
Packet Scheduler is not installed. 
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InterfaceBuffer 
[out] Pointer to the buffer containing the returned list of interface ieeeipins 


Return Values 
Successful completion returns the device name of the interface. 


Error code : Description | 
NO_ERROR The function executed without errors. 
ERROR_INVALID_HANDLE The client handle is invalid. 
ERROR_INVALID_PARAMETER One of the parameters is NULL. 
ERROR_INSUFFICIENT_BUFFER The buffer is too small to enumerate all 


interfaces. If this error is returned, the correct 
(required) size of the buffer is passed back | in 
pBufferSize. 


ERROR_NOT_ENOUGH_MEMORY The system is out of memory. 


Remarks 

The client calling the TcEnumeratelnterfaces function must first allocate a buffer, then 
pass the buffer to traffic control through /nterfaceBuffer. Traffic control returns a pointer 
to an array of interface descriptors in InterfaceBuffer. Each interface descriptor contains 
two elements: 

e The traffic control interface’s identifying text string. 


e The network address list descriptor currently associated with the interface. 


The network address list descriptor includes the media type, as well as a list of network 
addresses. The media type determines how the network address list should be 
interpreted: 


e For connectionless media such as a LAN, the network address list contains all the 
protocol-specific addresses associated with the interface. 


e For connection-oriented media such as a WAN, the network address list contains an 
even number of network addresses: 


e The first address in each pair represents the local (source) address of the interface. 


e The second address in each pair represents the remote eee address of 
the interface. 


Note Use of the TcEnumerateinterfaces function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 
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TcRegisterClient, CINotifyHandler 


TcGetFlowName 


The TcGetFlowName function provides the name of a flow that has been created by the 
calling client. Flow properties and other characteristics of flows are provided based on 
the name of a flow. Flow names can also be retrieved by a call to the 
TcEnumerateFlows function. 


Parameters 


FlowHandle 
[in] Handle for the flow. 


Strsize . 
[in] Size of the string buffer provided in pFlowName. 


pFlowName 
[out] Pointer to the output buffer holding the flow name. 


Return Values 


: Error codes Description 
NO_ERROR The function executed without errors. 
ERROR_INVALID_HANDLE The flow handle is invalid. 
ERROR_INVALID_PARAMETER One of the parameters is invalid. 
~ ERROR_INSUFFICIENT_BUFFER The buffer is too small to contain the results. 


Note Use of the TcGetFlowName function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. | | 
Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 
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TcEnumerateFlows 


TcModifyFlow 


The TeModifyFlow function modifies an existing flow. When calling TcModifyFlow, new 
flowspec parameters and any traffic control objects should be filled. 


Traffic control clients that have registered a ModifyFlowComplete handler (a mechanism 
for allowing traffic control to call the CIModifyFlowComplete callback function in order 


to alert clients of completed flow modifications) can expect a return value of 
ERROR_SIGNAL_PENDING. 


Parameters 


FlowHandle 
[in] Handle for the flow, as received from a previous call to the TeAddFlow function. 


pGenericFlow 
[in] Pointer to a description of the flow modifications. 


Return Values 


Error codes Description 
NO_ERROR The function executed without errors. 
ERROR_SIGNAL_PENDING The function is being executed 


asynchronously; the client will be called 
back through the client-exposed 
CiModifyFlowComplete function when 
the flow has been added, or when the 
process has been completed. 


ERROR_INVALID_ HANDLE The interface handle is invalid. 
ERROR_NOT_ENOUGH_MEMORY The system is out of memory. 
ERROR_INVALID_PARAMETER _ Aparameterisinvalid. = 
ERROR_INVALID_SERVICE_TYPE An unspecified or bad intserv service 

| type has been provided. 
ERROR_INVALID_TOKEN_RATE An unspecified or bad TokenRate value 


has been provided. 
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Error codes Description 


ERROR_INVALID_PEAK_RATE The PeakBandwiadth value is invalid. 
ERROR_INVALID_SD_MODE The ShapeDiscardMode is invalid. 
ERROR_INVALID_QOS_PRIORITY The priority value is invalid. 
ERROR_INVALID_TRAFFIC_CLASS The traffic class value is invalid. 
ERROR_NO_SYSTEM_RESOURCES There are not enough resources to 


7 accommodate the requested flow. 
-ERROR_TC_OBJECT_LENGTH_INVALID Bad length specified for the TC objects. 


ERROR_INVALID_DIFFSERV_FLOW Applies to Diffserv flows. Indicates that the 
QOS_DIFFSERV object was pase with 
an invalid parameter. 

ERROR_DS_MAPPING_EXISTS Applies to Diffserv flows. Indicates that the 
QOS_DIFFSERV_RULE specified in 
TC_GEN_FLOW already applies to an 
existing flow on the interface. 


ERROR_INVALID_SHAPE_RATE The QOS_OBJECT_SHAPING_RATE 
was passed with an invalid ShapeRate. 

ERROR_INVALID_DS_CLASS QOS_OBJECT_DS_CLASS is invalid. 

ERROR_NETWORK_UNREACHABLE | The network cable is not plugged into the 
adapter. 

Remarks 


If the TcModifyFlow function returns ERROR_SIGNAL_ PENDING, the 
CiModifyFlowComplete function will be called on a different thread than the thread that 
called the TcModifyFlow function. | 


Note Use of the TcModifyFlow function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
‘Header: Declared in Traffic.h. 

Library: Use Traffic. lib. 


TcEnumerateFlows, TcAddFlow, CiModifyFlowComplete 
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TcOpeninterface 


The TcOpeninterface function opens an interface. The TcOpeninterface function 
identifies and opens an interface based on its text string, which is available from a call to 
TcEnumeratelnterfaces.. Once an interface is opened, the client must be prepared to 
receive notification regarding the open interface, through traffic control’s use of the 
interface context. 


Parameters | . 


plnterfaceName | | 
[in] Pointer to the text string identifying the interface to be opened. This text string is 
part of the information returned in a previous call to TcEnumeratelnterfaces. 


ClientHandle 
[in] Handle used by traffic control to identify the client, obtained through the 
pClientHandle parameter of the client’s call to TcRegisterClient. 


ClifeCtx 
[in] Client’s interface—context handle for the opened interface. Used as a callback 
parameter by traffic control when communicating with the client about the opened 
interface. This can be a container to hold an arbitrary client-defined context for this 
instance of the interface. ; 


plfcHandle 
[out] Pointer to the buffer where traffic control can return an interface handle. The 


interface handle returned to p/fcHandle must be used by the client to identify the 
interface in subsequent calls to traffic control. 


Return Values | | 

Error code eer Description 
NO_ERROR The function executed without errors. 
ERROR_INVALID_PARAMETER | One of the parameters is NULL. 
ERROR_NOT_ENOUGH_ MEMORY _ The system is out of memory. 
ERROR_NOT_FOUND | : Traffic control failed to find an interface with 


| the name provided in pinterfaceName. 
ERROR_INVALID_ HANDLE | The client handle is invalid. 
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Note Use of the TcOpeninterface function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcEnumerateinterfaces, TcRegisterClient, CINotifyHandler 


TcQueryFlow 


The TeQueryFlow function queries traffic control for the value of a specific flow — 
parameter based on the name of the flow. The name of a flow can be retrieved from the 
TcEnumerateFlows function or from the TcGetFlowName function. 


Parameters 


FlowName — | 
[in] Name of the flow being queried. 


pGuidParam | | | 7 
[in] Pointer to the globally unique identifier (GUID) that corresponds to the flow. 
parameter of interest. A list of traffic control’ s GUIDs can be found in GUID. 7 


pBufferSize 
[in] Pointer to the size of the client- -provided buffer or the number of bytes used by 
traffic control. For input, points to the size of Buffer, in bytes. For output, points to the 
actual amount of buffer space written with returned en! data, in bytes. 


Buffer 
[out] Pointer to the client- -provided buffer in which the returned flow parameter i is 
written. 
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Return Values 

Error codes Description 

NO_ERROR The function executed without errors. 

ERROR_INVALID_ PARAMETER A parameter is invalid. 

ERROR_INSUFFICIENT_BUFFER The provided buffer is too small to hold the 
results. 

ERROR_NOT_SUPPORTED The requested GUID is not supported. 

ERROR_WMI_GUID_NOT_FOUND The device did not register for this GUID. 


ERROR_WMI_INSTANCE_NOT_FOUND __ The instance name was not found, likely 


, because the flow or the interface is in the 
process of being closed. 


Note Use of the TcQueryFlow function requires administrative privilege. 


SE 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic. lib. 


TcEnumerateFlows, T 


GetFlowName, GUID 


oO 


TcQuerylnterface 


The TeQuerylnterface function queries traffic control for related per-interface 
parameters. A traffic control parameter is queried by providing its Globally Unique 
Identifier (GUID). Setting the NotifyChange parameter to TRUE enables event 
notification on the specified GUID, after which notification events are sent to a client 
whenever the queried parameter changes. GUIDs for which clients can request 


notification are found in the GUID entry; the column titled “Notification” denotes which 
GUIDs are available for notification. 
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Parameters 

lfcHandle : 
[in] Handle associated with the interface to be queried. This handle is obtained by a 
previous call to the TcOpeninterface function. 


pGuidParam 
[in] Pointer to the globally unique identifier (GUID) that corresponds to the traffic 
control parameter being queried. 

NotifyChange 
[in] Used to request notifications from traffic control for the parameter being queried. If 
TRUE, traffic control will notify the client, through the CINotifyHandler function, upon 
changes to the parameter corresponding to the GUID provided in pGuidParam. 
Notifications are off by default. | 

BufferSize 7 | 
[in, out] Indicates the size of the buffer. For input, this value is the size of the buffer 
allocated by the caller. For output, this value is the actual size of the buffer, in bytes, 
used by traffic control. 7 

Buffer — | | 
[out] Pointer to a client-allocated buffer into which returned data will be written. 


Return Values - 

Note that, with regard to a requested notification state, only a return value of 

~ NO_ERROR will result in the application of the requested notification state. If a return 
value other than NO_ERROR is returned from a call to the TcQueryinterface function, 
the requested change in notification state will not be accepted. © | 


Error code | Description 
NO_ERROR ean The function executed without errors. 
ERROR_INVALID_HANDLE Invalid interface handle. 
ERROR_INVALID_ PARAMETER Invalid or NULL parameter. | 
ERROR_INSUFFICIENT_BUFFER The buffer is too small to store the results. 
ERROR_NOT_SUPPORTED Querying for the GUID provided is not 
supported on the provided interface. 
ERROR_WMI_GUID_NOT_FOUND The device did not register for this GUID. 


ERROR_WMI_INSTANCE_NOT_FOUND _ The instance name was not found, likely 
| because the interface is in the process of 
being closed. | 


Note Use of the TcQueryinterface function requires administrative privilege. 
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Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcEnumeratelinterfaces, TcRegisterClient, CINotifyHandler 


TcRegisterClient 


The TcRegisterClient function is used to register a client with the Traffic Control 
Interface (TCI). The TcRegisterClient function must be the first function call a client 
makes to the TCI. 


Client registration provides callback routines that allow the TCI to complete either client- 
initiated operations or asynchronous events. Upon successful registration, the caller of 
the TcRegisterClient function must be ready to have any of its TCI handlers called. See 
Entry Points Exposed by Clients of the Traffic Control Interface for more 
information. 


Parameters 


TciVersion 
[in] Traffic control version expected by the client, included to ensure compatibility 
between traffic control and the client. Clients can pass CURRENT_TCI_VERSION, 
defined in Traffic.h. 


CiRegCix 
[in] Client registration context. C/RegCtx is returned when the client’s notification 
handler function is called. This can be a container to hold an arbitrary client-defined 
context for this instance of the interface. 


pClientHandlerList 
[in] Pointer to a list of client-supplied handlers. Client-supplied handlers are used for 
notification events and asynchronous completions. Each completion routine is 
optional, with the exception of the notification handler. Setting the notification handler 
to NULL will return an ERROR_INVALID_PARAMETER. 
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pClientHandle 


[out] Pointer to the buffer that traffic control uses to return a registration handle to the 
client. 


Return Values 


Error code Description 

NO_ERROR | The function executed without errors. 

ERROR_NOT_ENOUGH_MEMORY The system is out of memory. 

ERROR_INVALID_PARAMETER | One of the parameters is NULL. 

ERROR_INCOMPATIBLE_TCI_VERSION The TCI version is wrong. 

ERROR_OPEN_FAILED Traffic control failed to open a system 
| device. The likely cause is insufficient 

privileges. 


Note Use of the TcRegisterClient function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. __ | 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcSetFlow 


The TcSetFlow function sets individual parameters for a given flow: 


Parameters , : 

pFlowName < : | a | ; : 
[in] Name of the flow being set. The value for this parameter is obtained by a previous 
call to the TcEnumerateFlows function or the TcGetFlowName function. 


pGuidParam 


[in] Pointer to the Globally Unique Identifier (GUID) that eotresponds to the parameter 
_ to be set. A list of available GUIDs can be found in GUID. 
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BufferSize 
[in] Size of the client-provided buffer. 


Buffer | 
[in] Pointer to a client-provided buffer. Buffer must contain the value to which the 
traffic control parameter provided in pGuidParam should be set. 


Return Values 

The TcSetFlow function has the following return values. 

Error codes | Description 

NO_ERROR | The function executed without errors. 

ERROR_NOT_READY The flow is currently being modified. 

ERROR_NOT_ENOUGH_MEMORY The buffer size was insufficient for the 
GUID. 

ERROR_INVALID_ PARAMETER Invalid parameter. 

ERROR_NOT_SUPPORTED etting the GUID for the provided flow is 
not supported. 

ERROR_WMI_INSTANCE_NOT_FOUND _ The instance name was not found, likely 


due to the flow or the interface being in 
| the process of being closed. 


ERROR_WMI_GUID_NOT_FOUND The device did not register for this GUID. 


Note Use of the TcSetFlow function requires administrative privilege. 


ae 


Fe 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

Library: Use Traffic.lib. 


TcSetinterface 


The TeSetinterface function sets individual parameters for a given interface. 
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Parameters 

lfcHandle 
[in] Handle associated with the interface to be set. This handle is obtained by a 
previous Call to the TcOpeninterface function. 

pGuidParam 
[in] Pointer to the globally unique identifier (GUID) that corresponds to the parameter 
to be set. A list of available GUIDs can be found in GUID. 

BufferSize 
[in] Size of the client-provided buffer. 

Buffer 
[in] Pointer to a client-provided buffer. Buffer must contain the value to which the 
traffic control parameter provided in pGuidParam should be set. 


Return Values 


Errorcodes _ Description 

NO_ERROR The function executed without errors. 
ERROR_INVALID_HANDLE Invalid interface handle. 
ERROR_INVALID_PARAMETER | Invalid parameter. 
ERROR_NOT_SUPPORTED Setting the GUID for the provided interface 


| is not supported. 
ERROR_WMI_INSTANCE_NOT_FOUND _ The GUID is not available. 
ERROR_WMI_GUID_NOT_FOUND The device did not register for this GUID. 


Note Use of the TcSetinterface function requires administrative privilege. The list of 
GUIDS that can be set is explained in GUID. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 

Header: Declared in Traffic.h. 

aes Use Traffic.lib. 


Entry Points Exposed by Clients of the Traffic Control 
Interface 


When registering as a client of the traffic control jerace the user is expected to 
provide a list of entry points, which can be called by the TCI. These are defined in this 
section. | | | 
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e ClAddFlowComplete 

e CiDeleteFlowComplete 
° ClModifyFlowComplete 
e CINotifyHandler 


ClAddFlowComplete 


The ClAddFlowComplete function is used by traffic control to notify the client of the 
completion of its previous call to the TeAddFlow function. 


The ClAddFlowComplete callback function is optional. If this function is not specified, 
TcAddFlow will block until it completes. 


Parameters 


CIFlowCtx 
[in] Client provided—flow context handle. This can be the container used to hold an 
arbitrary client-defined context for this instance of the client. This value will be the 
same as the value provided by the client during its corresponding call to TcAddFlow. 


Status 
[in] Completion status for the TcAddFlow request. This value may be any of the 


return values possible for the TcAddFlow function, with the exception of 
ERROR_SIGNAL_PENDING. 


Note Use of the ClAddFlowComplete function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 


TcAddFlow 
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CiDeleteFlowComplete 
The ClDeleteFlowComplete function is used by traffic control to notify the client of the 


completion of its previous call to the TcDeleteFlow function. 


The CiDeleteFlowComplete callback function is optional. If this function is not specified, 
TcDeleteFlow will block until it completes. 


Parameters © 
CIFlowCtx 
[in] Client provided—flow context handle. This can be the container used to hold an 
arbitrary client-defined context for this instance of the client. This value will be the 
~same as the value provided by the client during its corresponding Call to 
TcDeleteFlow. 


Status 
[in] Completion status for the TcDeleteFlow request. This value may be any of the 
return values possible for the TcDeleteFlow function, with the exception of 
ERROR_SIGNAL_PENDING. 


Note Use of the ClIDeleteFlowComplete function requires administrative privilege. 


| Windows N NT/2000: Requires Windows 2000. 
~Windows 95/98: Unsupported. 


TcDeleteFlow 


- CiModifyFlowComplete 
The CIModifyFlowComplete function is used by traffic control to notify the client of the 


completion of its previous call to the TcModifyFlow function. 


The CIModifyFlowComplete callback function is optional. If this function is not 
specified, TeModltyFlow will block until it completes. ae 
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Parameters 


CIFlowCtx 
[in] Client provided—flow context handle. This can be the container used to hold an 
arbitrary client-defined context for this instance of the client. This value will be the © 


same as the value provided by the client during its corresponding call to 
TcModifyFlow. 


Status 
[in] Completion status for the TcModifyFlow request. This value may be any of the 


return values possible for the TcModifyFlow function, with the exception of 
ERROR_SIGNAL_PENDING. 


Note Use of the CiIModifyFlowComplete function requires administrative privilege. 


oo 


Soon 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 


TcModifyFlow 


CINotifyHandler 


The CiINotifyHandler function is used by traffic control to notify the client of various 
traffic control—specific events, including the deletion of flows, changes in filter 
parameters, or the closing of an interface. 


The CINotifyHandler callback function should be exposed by all clients using traffic 
control services. 
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Parameters 

CiRegCtx 
[in] Client registration context, provided to traffic control by the client with the client’s 
call to the TcRegisterClient function. 

CilfcCtx 
[in] Client interface context, provided to traffic control by the client with the client’s call 
to the TcOpeninterface function. Note that during a TC_ NOTIFY_ IFC_UP event, 
CilfeCtx is not available and will be set to NULL. 

Event 
[in] Describes the notification event. See the Remarks section for a list of notification 
events. | 

SubCode 

— [in] Value used to further qualify a notification event. 

BufSize 
[in] Size of the buffer included with the notification event. 

Buffer 
[in] Buffer containing the detailed event information associated with Event and 
SubCode. 


Remarks 

Notification events may require the traffic control client to take particular action or 
respond appropriately, for example, removing filters or enumerating flows for affected 
interfaces. 


The following table describes the various notification events. 


Buffer 
Event SubCode contents Remarks 
TC_NOTIFY_ None InterflaceName Anew traffic control interface is coming 
IFC UP of the new up, and the list of addresses is indicated. 
= interface 3 
TC_NOTIFY_ Reason for InterfaceName __ Indicates an interface that was opened 
IFC_CLOSE close of the new by the client is being closed by the 
interface system. Note that the interface and its 
supported flows and filters are closed by 
the system upon return from the 
notification handler. The client does not | 
need to close the interface, delete flows, 
og, i8 | or delete filters. © 
TC_NOTIFY_ ~None New parameter Used to notify clients that have 
IFC_CHANGE | value registered for interface change 


notification through the NotifyChange 
parameter of the TcQuerylnterface 
function. 


(continued) 
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(continued) 

Event SubCode 

TC. NOTIFY_ Pointer to the 

PARAM CHANG GUID fora 

ED traffic control 
parameter 
queried using 
the 
TcQueryinterf 
ace function. 

TC_NOTIFY_ CIFlowCix 

FLOW_CLOSE 


Buffer 
contents 


New parameter . 


value 


InterfaceName 
of the closed 
interface 


Remarks 


This event is notified as a result of a 
change in a parameter previously 


queried with the NotifyChange flag set. 


Indicates system closure of a client- 
created flow. The system deletes all 
associated filters. 


Note Use of the CINotifyHandler function requires administrative privilege. 


Windows NT/2000: Requires Windows 2000. 


Windows 95/98: Unsupported. 


Traffic Control Structures 


This section describes the following traffic control structures: 


IP_PATTERN 


TC_GEN_FILTER > 
TC_GEN_FLOW | 


QOS_DIFFSERV_RULE 


TC_IFC_DESCRIPTOR 
TCL CLIENT_FUNC_LIST 


ADDRESS _LIST_DESCRIPTOR 
ENUMERATION_BUFFER 


There is also a collection of structures associated with traffic control that enable 
application developers to query or gather statistical information regarding the packet 
scheduler and its traffic control faculties. That collection of statistic-enabling structures is 


— the following: 
e GUID 


e PS COMPONENT_STATS 
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e PS_ADAPTER_STATS 

e PS_FLOW_STATS 

e PS _CONFORMER_STATS 
e PS_SHAPER_STATS 

e PS _DRRSEQ_ STATS 


Many structures explained in this section work closely with the FLOWSPEC structure. 


ADDRESS_LIST_DESCRIPTOR 


The ADDRESS_LIST_DESCRIPTOR structure provides network address descriptor 
information for a given interface. For point-to-point media such as WAN connections, the 
list is a pair of addresses, the first of which is always the local or source address, the 
second of which is the remote or destination address. Note that the members of 
ADDRESS_LIST_DESCRIPTOR are defined in Ntddndis.h. 


Members 

MediaType | 
Pointer to the media type of the interface. NDIS_MEDIUM is a defined type from 
definitions provided in Ntddndis.h. 

AddressList 
Pointer to the address list for the interface. NETWORK_ADDRESS_LIST is defined in 
Ntddndis.h. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


~ENUMERATION_ BUFFER 


The ENUMERATION _ BUFFER structure contains information specific to a given flow, 
- including flow name, the number of filters associated with the flow, and an array of filters 
associated with the flow. | 


Volume 1 Winsock and QOS 


836 


ss 
Seioeee 


Members 
Length 


Number of bytes from the beginning of the ENUMERATION_BUFFER to the next 


ENUMERATION_BUFFER. 


OwnerProcessid 


Identifies the owner of the process. 


FlowNameLength 


Specifies the length of the FlowName member. 


FlowName 


Array of WCHAR characters, of length MAX_STRING_LENGTH, that specifies the 


flow name. 


pFlow 
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Reserved 
Reserved for future use. 


eserved2 
Reserved for future use. 


rcAddr 
Source address. 


stAddr 
Destination address. 


rotocolid 
Protocol identifier. 


eserved3 
Reserved for future use. 


tcSrcPort 
Source port. 


tcDstPort 
Destination port. 


tclompType 

ICMP message type 
tclompCode 

ICMP message code. _. 


tcSpi 
Service provider interface. 


844 Volume 1 Winsock and Qos 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


QOS_DIFFSERV_RULE 


The QOS_DIFFSERV_RULE structure is used in conjunction with the traffic control 
object QOS_OBJECT_DIFFSERV to provide Diffserv rules for a given flow. 


Members 


InboundDSField 
Diffserv code point (DSCP) on the inbound packet. InboundDSField must be unique 
for the interface, otherwise the flow addition will fail. 


Valid range is OxO0—Ox8F. 


ConformingOutboundDSField 
Diffserv code point (DSCP) marked on all conforming packets on the flow. This 
member can be used to re-mark the packet before it is forwarded. 


Valid range is OxO0O-—Ox3F. 


NonConformingOutboundDSField 
Diffserv code point (DSCP) marked on all nonconforming packets on the flow. This 
member can be used to remark the packet before it is forwarded. 


Valid range is OxOO—Ox3F. 


ConformingUserPriority 
UserPriority value marked on all conforming packets on the flow. This member can be 
used to remark the packet before it is forwarded. 


Valid range is 0-7 


NonConformingUserPriority 
UserPriority value marked on all nonconforming packets on the flow. This member 
can be used to remark the packet before it is forwarded. 


Valid range is 0-7 
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Windows NT/2000: Requires Windows 2000. | 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


QOS_OBJECT_DIFFSERV 


TC_GEN_FILTER 


The TC_GEN_FILTER structure creates a filter that matches a certain set of packet 
attrioutes or criteria, which can subsequently be used to associate packets that meet the 
attribute criteria with a particular flow. The TC_GEN_FILTER structure uses its 
AddressType member to indicate a specific filter type to apply to the filter. 


Members 


AddressType _ : | 


Defines the filter type to be applied with the filter, as defined in Ntddndis.h. With the 
designation of a specific filter in AddressType, the generic filter structure 
TC_GEN_FILTER provides a specific filter type. 


PatternSize 
Size of the Pattern member. 


Pattern 


Indicates the specific format of the pattern to be applied to the filter, such as 
IP_PATTERN. The pattern specifies which bits of a given packet should be evaluated 
when determining whether a packet is included in the filter. 


Mask 


A bitmask applied to the bits designated in the Pattern member. The application of 
the Mask member to the Pattern member determines which bits in the Pattern 
member are significant (should be applied to the filter criteria). Note that the Mask 
member must be of the same type as the Pattern member. | 
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indows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


TC_GEN_FLOW 


The TC_GEN_FLOW structure creates a generic flow for use with the traffic contro 
interface. The flow is customized through the use of the structure’s members. | 


Members 


SendingFlowspec 
FLOWSPEC structure for the sending direction of the flow. 


ReceivingFlowspec 
FLOWSPEC structure for the receiving direction of the flow. 


TcObjectsLength 
Length of TcObjects. 


TcObjects 
Buffer that contains an array of traffic control objects specific to the given flow. The 
TcObjects member can contain objects from the list of currently supported objects. 
Definitions of these objects can be found in Qos.h and Traffic.h: 


QOS_OBJECT_DS_CLASS 
QOS_OBJECT_TRAFFIC_CLASS 
QOS_OBJECT_DIFFSERV 
QOS_OBJECT_SD_MODE 
QOS_OBJECT_SHAPING_RATE 
QOS_OBJECT_END_OF_LIST 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. — : 
Header: Declared in Traffic.h. 
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-FLOWSPEC 


TC_IFC_DESCRIPTOR 


The TC_IFC_DESCRIPTOR structure is an interface identifier used to enumerate 
interfaces. 


Members 
Length 


Number of bytes from the beginning of the TC_IFC_DESCRIPTOR to the next © 
TC_IFC_DESCRIPTOR. 


pinterfaceName 


Pointer to a zero-terminated Unicode string representing the name of the packet — 


shaper interface. This name is used in subsequent TC API calls to reference the 
interface. | | | 


pinterfacelD 


‘Pointer to a zero-terminated Unicode string naming the DeviceName of the interface. 
AddressListDesc 


Network address list descriptor. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


TCI CLIENT _FUNC_LIST 


The TCI_CLIENT_FUNC _LIST structure is used by the traffic control interface to register 
and then access client-callback functions. Each member of TCI_CLIENT_FUNC_LIST is 
a pointer to the client provided—callback function. | 
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Members — 
CINotifyHandler 
Pointer to the client-callback function otifyHandler. 


ClAddFlowCompleteHandler 
Pointer to the client-callback function ddFlowCompleteHandler. 


CiModifyFlowCompleteHandler 
Pointer to the client-callback function CIModifyFlowCompleteHandler. 


CiDeleteFlowCompleteHandler 
Pointer to the client-callback function eleteFlowCompleteHandler. 


Remarks 


Any member of the TCI CLIENT_FUNC_LIST structure can be NULL except 
TCL NOTIFY_HANDLER. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


CINotifyHandler, C[AddFlowComplete, CIModifyFlowComplete, 
CiDeleteFlowComplete 


GUID 


Traffic control uses GUIDs to convey information about the status of packet shaper 
___ interfaces, to report errors, and to provide statistics. 


The GUID_QOS_STATISTICS_ BUFFER structure is actually an array of 
PS_COMPONENT_STATS structures, which in turn serve as a container structure, 
holding one of the five following structures in its Stats member. 


e PS ADAPTER_STATS 


e PS FLOW_STATS 
e PS_CONFORMER_STATS 


e PS_SHAPER_STATS 
e PS DRRSEQ_ STATS 
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The following table lists GUIDs used with packet shaper on Windows 2000 QOS-enabled 
computers. In the scope column, P/I indicates that the GUID is based per-interface, and 
P/F indicates it is based per-flow. 


GUID 


GUID_QOS_ 
REMAINING_ 
BANDWIDTH 


GUID_QOS_ 
LATENCY 
GUID_QOS_ 
FLOW_COUNT 


GUID_QOS_NON_ 


BESTEFFORT_ | 
LIMIT 


GUID_QOS_ MAX. 


~OUTSTANDING_ 
SENDS 


GUID_QOS_ 
STATISTICS _ 
BUFFER 


GUID_ 
QOS _ 
FLOW_ 
MODE 


GUID_QOS_ 
ISSLOW_ 
FLOW — 


Size 


ULONG 


ULONG 
ULONG 


ULONG 


ULONG 


See the 
following. 


ULONG 


ULONG 


Scope 


P/| 


P/| 
P/I 


P/I 
P/I 


Pil, 
P/F 


P/| 


P/F 


Set- 
table? 


No 


No 
No 


No 


No 


Yes 


Yes 


No 


Notifi- 
cation? 


Yes 


No 
Yes 


No 


No 


No 


No 


No — 


Description 


The remaining amount of 
reservable bandwidth on this — 
interface. 7 | 


The latency of this interface. 
Number of active flows. 


The total amount of reservable 
bandwidth. 


Maximum number of sends | 
that can be outstanding on this 
interface. 


Statistics collected for flow or 
interface. The 
GUID_QOS_ STATISTICS __ 
BUFFER structure is actually 
an array of | 
PS_COMPONENT_STATS 
structures, as described in the 


preceding. 


Mode of operation for this 
interface: STANDARD or 
DIFFSERV. Note that you 
must specify the constants 
rather than Standard or > 


| _ Diffserv when using this GUID. 


Indicates an ISSLOW flow. 


(continued) 
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(continued) 

Set- Notifi- 
GUID Size Scope table? cation? Description 
GUID_QOS_ ULONG none No No Timer resolution, in 
TIMER_ microseconds. 
RESOLUTION | 
GUID_QOS_ ULONG P/F No No The conforming DSCP value 
FLOW_IP_ for this flow. 
CONFORMING 
GUID_QOS_FLOW_ ULONG P/F No No The nonconforming SCP value 
IP_ for this flow. 
NONCONFORMING 
GUID_QOS_FLOW_ ULONG P/F No No The conforming 802.1p value 
8021P_ for this flow 
CONFORMING 
GUID_QOS_FLOW_ ULONG P/F No No The nonconforming 802.1p 
8021P_ value for this flow. 


NONCONFORMING 


Remarks 


In the GUID_QOS_STATISTICS_BUFFER GUID described in the table above, you must 
pass in a buffer that is large enough to hold all returned PS_COMPONENT_STATS 
structures. 


Version: Requires MAPI 1.0 or later. 
Header: Declared in Mapiguid.h. 


PS_COMPONENT_STATS 


The PS_COMPONENT_STATS structure enables applications to get statistical 
information regarding their TC-enabled flow. This structure obtains information from 
GUID_QOS_STATISTICS_BUFFER GUID. This GUID actually is an array of 

PS _COMPONENT_STATS, with each element of that array (each 
PS_COMPONENT_STATS structure) containing one of the five PS_* structure types 
explained subsequently. | 
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Members | 


Type 
Indicates one of the following types of PS_* structure contained in the Stats member: 


e PS_ADAPTER_STATS 
e PS_FLOW_STATS | 7 | 

e PS_CONFORMER_STATS 

e PS_SHAPER_STATS 

e PS DRRSEQ_STATS | 


Length 
Length of the Stats member, in bytes. 


Stats i | 
Array of structures of the type indicated in the Type member. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. me 


PS_ADAPTER_STATS 


The PS_ADAPTER_STATS structure provides statistical packet shaper information 
about a specified adapter. Note that the PS_ADAPTER_STATS structure is used in 
conjunction with the PS_COMPONENT_STATS structure. 


ee 


ro 
pastas 
Soren 


= 
ae 
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Members 


OutOfPackets 


Number of instances in which the adapter had no packets to transmit on the specified 
adapter. 


FlowsOpened 
Number of flows opened on the adapter. 


FlowsClosed 
Number of flows closed on the adapter. 


FlowsRejected 
Number of flows that were rejected due to packet shaper constraints on the adapter. 


FlowsModified 
Number of flows that were modified on the adapter. 


FlowModsRejected 


Number of flow modifications that were rejected on the adapter due to packet shaper 
constraints. 


MaxSimultaneousFlows 
Maximum number of simultaneous flows. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. 


PS_FLOW_STATS 


The PS_FLOW_STATS structure provides statistical packet shaper information about a 


particular flow. Note that the PS_FLOW_STATS structure is used in conjunction with the 
PS_COMPONENT_STATS structure. 


embers 


DroppedPackets | 
Number of packets that have been dropped from the flow. 
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PacketsScheduled 


Number of packets that have been scheduled for transmission on the flow. 
PacketsTransmitted 

Number of packets that have been transmitted on the flow. 
BytesScheduled 

Number of bytes that have been scheduled for transmission on the flow. 
BytesTransmitted 

Number of bytes that have been transmitted on the flow. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. 


PS_CONFORMER_STATS 


The PS_CONFORMER_STATS structure provides statistical packet shaper information 


about a particular flow. Note that the PS_ CONFORMER_STATS structure is used in 
conjunction with the PS_COMPONENT_STATS structure. 


Members 


NonconformingPacketsScheduled 
Number of nonconforming packets that have been scheduled on the flow or interface. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. 


PS SHAPER STATS 


The PS_SHAPER_STATS structure provides statistical packet shaper information about 
the computer’s Windows 2000 packet shaper component. Note that the — 

PS SHAPER_STATS structure is used in conjunction with the 

PS COMPONENT_STATS structure. 
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Members | | 


MaxPacketsInShaper 
Maximum number of packets that have been in the packet shaper for the flow or 
interface. 


AveragePacketsinShaper 
Average number of packets that have been in the packet shaper for the flow or 
interface. _— 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. 


PS DRRSEQ STATS 


The PS_DRRSEQ_STATS structure provides network interface card (NIC) and packet 
sequencer-—packet shaper statistics. Note that the PS_DRRSEQ_STATS structure is 
used in conjunction with the PS_COMPONENT_STATS structure. 


Members 


MaxPacketsInNetcard 
Maximum number of packets that have been queued in the network interface card for 
the flow or interface. | tee, 3a % 


AveragePacketsinNetcard | 
Average number of packets queued in the network interface card for the flow or 
interface. 4 | 


MaxPacketsinSequencer | | 
Maximum number of packets that have been queued in the packet sequencer for the 
flow or interface. 
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AveragePacketsInSequencer 
Average number of packets that have been queued in the packet sequencer for the 
flow or interface. 


NonconformingPackets Transmitted 


Number of nonconforming packets that have been transmitted for the flow or 
interface. | 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Ntddpsch.h. 


Tratfic Contro! Objects 


Applications that require specific or granular traffic control, beyond what is available in 
the TC API, can use traffic control objects. The use of traffic control objects with the TC 
API is similar to the use of QOS Objects with the QOS API. 


Like QOS objects, traffic control object follow a stringent structure. Traffic cat objects 
always include an information header that specifies the type and length of the traffic 
control object to which it is attached, followed by the object itself. 


Some objects are shared by Qos and traffic control. Those @ objects are e defined in the 
QOS Objects section, and are the following: 

e QOS OBJECT SD MODE 

e QOS_OBJECT_SHAPING_RATE 


This section describes the following traffic control objects: 


e QOS OBJECT TRAFFIC CLASS 
¢ QOS_OBJECT_DS_CLASS 
¢ QOS OBJECT _DIFFSERV 


As with Qos objects, traffic control objects begin each object with the 
QOS_OBJECT_HDR, which is used by QOS components that interrogate QOS objects 
to ascertain the type of object that follows the header. | 
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QOS_OBJECT_TRAFFIC_CLASS 


The traffic control object QOS_OBJECT_TRAFFIC_CLASS is used to override the 
default UserPriority value ascribed to packets that classify to (are associated with) a 
given flow. By default, the UserPriority value of a flow is derived from the ServiceType; 
the capability to override the default UserPriority is necessary because packets can be 
tagged in their Layer 2 headers (such as an 802.1p header) to specify their priority to 
Layer-2 devices. Using QOS_OBJECT_TRAFFIC_CLASS enables application 
developers to override the default UserPriority setting. 


Members 


ObjectHdr 


The QOS object QOS_OBJECT_HDR. The object type for this traffic control object 
should be QOS_OBJECT_TRAFFIC_CLASS. 


TrafficClass 
User priority value of the flow. The valid range is zero through seven. The following 


settings are chosen (by default) when the QOS_OBJECT_TRAFFIC_CLASS traffic 
control object is not used. 


Service Types Traffic Class Default Value 
ServiceTypeBestEffort, 0 

ServiceTypeQualitative 

ServiceTypeControlledLoad 4 

ServiceTypeGuaranteed 5 
ServiceTypeNetworkControl 7 

Non Conformant traffic 1 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


QOS_DIFFSERV_RULE, @QOS_OBJECT_DS_CLASS, QOS_OBJECT_DIFFSERV 
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QOS_OBJECT_DS_CLASS 


developers to 


ion 


t 


Ica 


CLASS enables appl 


override the default Diffserv code point (DSCP) value for the IP packets associated with 


ect QOS_OBJECT_DS 


The traffic control obj 


flow. By default, the DSCP value 


Type. 


Ice 


derived from the flow’s Servi 


IS 


a given 


Members 


ObjectHdr 
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QOS_OBJECT_DIFFSERV 


The QOS_OBJECT_DIFFSERV traffic control object is used to specify filters for the 
packet scheduler when it operates in Differentiated Services Mode. 


Members 


ObjectHdr 
The QOS object QOS_OBJECT_HDR. The object type for this traffic control object 
should be QOS_OBJECT_DIFFSERV. 


DSFieldCount 
Number of Diffserv Rules in on this object. 


DiffservRule 
Array of QOS_ DIFFSERV_RULE structures. 


Remarks 


The QOS_OBJECT_DIFFSERV object is used to specify the set of Diffserv rules that 
apply to the specified flow, all of which are specified in the DiffservRule member. Each 
Diffserv rule has an InboundDSField, which signifies the DSCP on the Inbound packet. 
The Diffserv Rules also have an OutboundDSCP and UserPriority values for conforming 
and non conforming packets. These indicate the DSCP and 802.1p values that go out on 
the forwarded packet. Note that the DSCP or UserPriority mapping based on 
ServiceType or QOS_ OBJECT_DS_CLASS or QOS_OBJECT_TRAFFIC_CLASS is - 
not- used in this mode. 


Windows NT/2000: Requires Windows 2000. 
_ Windows 95/98: Unsupported. 
Header: Declared in Traffic.h. 


QOS DIFFSERV_ RULE, QOS OBJECT DS CLASS, 
QOS OBJECT TRAFFIC CLASS 
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CHAPTER 17 


Local Policy Module API Reference 


The Local Policy Module (LPM) API is a set of functions that the Policy Control Module 
(PCM) uses to interact with one or more LPMs. LPM API functions must be exported by 
LPMs to allow the PCM to invoke the LPM. This approach enables multiple LPMs to 
interact with the PCM, and subsequently, allows the PCM to return policy based— 
admission control decisions from one or more LPMs to the Admission Control Service 
(ACS). This concept is similar to a three-tiered approach, and enables multiple LPMs to | 
easily coexist on a single system. Note, too, that LPMs may selectively accept or pe 
individual flows within a given policy based—decision request. 


LPM Functions 


The following functions are exposed by the Microsoft-provided LPM, Msidlpm.dll. 


e cbpAdmitRsvpMsg 
e cbpGetRsvpObjects 


The following functions must be exposed by each LPM; they allow the PCM to 
communicate requests from the Subnet Bandwidth Manager (SBM) (through the PCM). 
The Microsoft-supplied LPM, implemented as a DLL in Msidlpm.dll, also uses this API. 
Note that callback functions, identified by their cbp prefix, should not be exposed by 
LPMs; these callback functions, which are exposed by the os facilitate deferred 
response from LPMs to PCM requests. 
e LPM_AdmitRsvpMsg 
e LPM_CommitResv 

_ @ LPM_Deinitialize 
¢ LPM_DeleteState 
¢ LPM_GetRsvpObjects 
° LPM_Initialize 
¢@ Lpm_lIpAddressTable 
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cbpAdmitRsvpMsg 


The cbpAdmitRsvpMsg function is used by LPMs to return results for the 
LPM_AdmitRsvpMsg request. LPMs should only use this function if they have returned 
LPM_RESULT_DEFER to the LPM_AdmitRsvpMsg function call. The PCM will only 
accept results from this function within the result-time limit established by each LPM 
through the ResultTimeLimit parameter of the LPM_Initialize function. 


Parameters 


LpmHandle | 
[in] Unique handle for the LPM, as supplied in LPM_Initialize. The PCM will ignore 


any result that is not accompanied by a valid LPM handle. 


RequestHandle 
[in] Unique handle that distinguishes this request from all other requests. LPMs must 


pass this handle to the PCM when returning results asynchronously for an individual 
request by calling cbpAdmitRsvpMsg. RequestHandles become invalid once results 
are returned, requiring each request to get its own unique RequestHandle from 


the PCM. 


LpmPriority Value 
[in] LPM Priority Value assigned to the request. The PCM assumes 


LPV_DONT_CARE if LomPriorityValue is invalid. 


PolicyErrorCode 
[in] Policy error code value. PolicyErrorCode must be a nonzero value; the SBM will 
copy this value, in combination with PolicyErrorValue, into the RSVP Error Object 
when sending PATHERR or RESERR messages (as the result of policy based— 
admission control failure, to provide a reason for rejecting the request). 


PolicyErrorValue 
[in] Policy error value. PolicyErrorValue must be a nonzero value; the SBM will copy 
this value, in combination with PolicyErrorCode, into the RSVP Error Object when 
sending PATHERR or RESERR messages (as the result of policy based—admission 
control failure, to provide a reason for rejecting the request). 


Reserved 
[in] This parameter is reserved for future use. 
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Remarks 


When a request has been rejected, the PCM will call the LPM to instruct it to delete the 
request’s state. The LPM can choose to delete the request’s state at any time during the 
rejection process. If the LPM deletes a request’s state shortly after its rejection of the 
request, the LPM must be prepared to handle subsequent calls (by the PCM, through 
the LPM_DeleteState function) to delete the (already deleted) state. 


The LPM does not need to maintain state for requests to which it returns 
LPV_DONT_CARE. However, the LPM must be prepared to handle LPM_DeleteState 
requests for this (nonexisting) state. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 


cbpGetRsvpObjects 


The cbpGetRsvpObjects function is a callback function for LPMs to asynchronously 
return results for LPM_GetRsvpObjects requests. LPMs call the cbpGetRsvpObjects 
function to asynchronously return policy data objects to the PCM for an _ 
LPM_GetRsvpObjects request. An LPM should only use the cbpGetRsvpObjects 
function if it returned LPM_RESULTS_DEFER to the PCM’s LPM_GetRsvpObjects 
request. 


arameters 


LpmHandle | Be | | 
in] Unique handle for the LPM, as supplied in LPM_Initialize. The PCM will ignore 
any result that is not accompanied by a valid handle. 


RequestHandle | 3 | | 
[in] Unique handle that distinguishes this request from all other requests, provided 
_ from the corresponding LPM_GetRsvpObjects request. 


LomError ee 
[in] Error value, used by the PCM to determine whether the policy data objects 
returned with this function should be used. Any value other than LPM_OK will result in 
the PCM ignoring the contents of *AsvpObjects. 
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Note that if an LPM is returning an error, it should free buffers allocated during the 
LPM_GetRsvpObjects request processing; these buffers should have been allocated 
using the MemoryAllocator function, supplied within the LPM_Initialize function as 
its FreeMemory parameter. 


lf no policy data objects are being returned, LomError must be set to LPM_OK, 
RsvpObjectsCount must be set to zero, and *RsvpObjects must be set to NULL. The 
LPM can force the SBM to stop sending out the RSVP message by setting the value 
of LomErrorto LPV_DROP_MSG. | 


_ RsvpObjectsCount 


[in] Number of policy data objects being returned. If no policy data objects are being 
returned, LomError must be set to LPM_OK, RsvpObjectsCount must be set to zero, 
and *RsvoObjects must be set to NULL. 


RsvpObjects 
[in] Array of pointers to policy data object. The buffer containing the policy data 
objects should be allocated using the MemoryAllocator function supplied within the 
LPM_Initialize function. The Subnet Bandwidth Manager (SBM) will free the policy 
data objects when they are no longer needed. 


If no policy data objects are being returned, LomError must be set to LPM_OK, 
RsvpObjectsCount must be set to zero, and *RsvpObjects must be set to NULL. 


Remarks | 

LPMs do not need to send policy data options if only default options are required. Since 
the content of policy data objects are opaque to the PCM, no host-to-network order 
conversion of policy element headers and contents will be done by the PCM; the PCM 
expects LPMs to generate policy elements in the network order such that the receiver of 
the policy elements can correctly parse them. However, the policy data object header 
must be in host order to allow the PCM to merge policy oenen: AW possible or 
applicable). | 


From LPMs that support all PE types, the PCM expects asmciste policy data objects and 
their required policy data options. Furthermore, the PCM expects the policy data object 
header to be in host order; it is the responsibility of the LPM to process the host-to- 
network order conversions of policy options and policy elements. 


If any LPM returns LPV_DROP_MSG, the SBM will not send out an RSVP refresh 
message, but will free the policy data objects returned by other LPMs (those that did not 


~ return LPV_DROP_MSG, if any). By not sending out RSVP refresh messages, a flow’s 


RSVP state both upstream and downstream will begin to age, and eventually get 


deleted. 


Note The SBM will send out the RSVP refresh message even if some or all LPMs fail to 


return policy data objects in a timely fashion, even though such an outgoing RSVP 
message may not contain all policy data objects it should. | 
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Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 


LPM_AdmitRsvpMsg 


The LPM_AdmitRsvpMsg function is called by the PCM to pass RSVP messages to the 
LPM for policy based—admission control decisions. Results from calling 
LPM_AdmitRsvpMsg can be passed back to the PCM either synchronously or 
asynchronously by setting the return value appropriately. Asynchronous results should 
be returned by calling the cbpAdmitRsvpMsg function. 


Parameters 


PemReqHandle a . 
in] Unique handle that identifies this request from all other requests. LPMs must pass 


this handle to the PCM when returning results asynchronously for an individual 
request by calling cbpAdmitRsvpMsg. PemReqHandles become invalid once results 
are returned, requiring each request to get its own unique PemReqHandle from 


the PCM. 
pRecvdintf 
[in] Pointer to the interface on which the message was received. The received 
interface IP address is supplied as the RSVP HOP object, and the Logical Interface 
Handle is set to the SNMP Index. Note that interface index numbers can change with 
the addition and deletion of interfaces, due to the Plug and Play features of 
Windows 2000. : 
pRsvpMsgObjs | | | 
in] Objects received from RSVP. The SBM unpacks received RSVP messages into 
individual objects and converts the contents of such RSVP objects into host order, 
and supplies them in the RSVP_MSG_OBwS structure, which is defined in lpmapi.h. 
The following objects are supplied. ra 
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RevdRsvpMsgLength 

Value Meaning 

RsvpMsgType RSVP message type, as defined by the RSVP protocol. 

RsvpSession Pointer to the RSVP session, as defined by the RSVP 
protocol. Note that contents are in host order. 

RsvopFromHop Pointer to the hop from which the RSVP message was 
received. Note that contents are in host order. 

RsvpScope Pointer to the RSVP scope object. 

RsvpStyle Pointer to the RSVP reservation style, as defined by the 


RSVP protocol. Note that contents are in host order. 
FlowDescListCount Number of flow descriptors. 
FlowDescList Array of flow descriptor pointers. 
PolicyDataCount Number of policy data objects. 


PolicyDataObjects Array of policy data object pointers. Note that only the RSVP 
object header and the policy options are converted to host 
order, but policy element headers as well as contents are left 
in network order; the PCM cannot convert the latter to host 
order, because the PCM cannot parse policy elements. Note 
that the Microsoft-provided LPM, Msidlipm.dll, does reorder 
policy element content into host order. 


ErrorSpec Pointer to the received RSVP ERROR_SPEC object. 
RevdRsvpMsgLength 

[in] Length of the received RSVP message, in bytes. 
RevdRsvpMsg 

[in] RSVP message, in network order. 
pulPcmActionFlags | 


[out] Flags used to specify an action requested of the PCM. The LPM can currently 
set this parameter to FORCE_IMMEDIATE_REFRESH to request an immediate 
refresh of the message being admitted. An LPM can set this flag if a change in policy 
data is detected that it wants to forward immediately. Before sending, the SBM asks 
the LPM to supply policy information for the outgoing refresh message. 

Note that LPMs do not need to set this flag when a new PATH message is being 
accepted; SBMs automatically send the new PATH message toward receivers. 


pPolicyDecisions 
[out] Pointer to policy decisions. An LPM must allocate this buffer using the memory 
allocator supplied in the LPM_Initialize function call; the SBM frees the buffer after 
acting on pPolicyDecisions. The PCM looks at pPolicyDecisions only when the 
function returns LPM_RESULT_READY. Synchronous policy decisions must be 

_ returned for each flow in FlowDescList, and the number of entries in the 

pPolicyDecisions array must be equal to FlowDescListCount. Each policy decision 
consists of the following. 7 
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Value Meaning 


LpmPriorityValue Pointer to a buffer to receive the LPM Priority Value from the 
LPM. Note that the PCM will only look at this parameter if the 
return value of LPM_AdmitRsvpMsg is set to 
LPM_RESULT_READY. If the LPM is returning results 
synchronously, this parameter must be set to a valid priority 
value. See Local Policy Module for more information. 


PolicyErrorCode Pointer to a policy error code. If the request is being rejected 
synchronously, LPMs must provide a nonzero value for this 
parameter; the SBM will copy this value, in combination with 
PolicyErrorValue, into the RSVP error object when sending 
PATHERR or RESVERR messages (as the result of policy 
based—admission control failure, to paneee a reason for 
rejecting the request). 


PolicyErrorValue Pointer to a policy error value. If the request is being rejected 
synchronously, LPMs must provide a nonzero value for this — 
parameter; the SBM will copy this value, in combination with 
PolicyErrorCode, into the RSVP error object when sending 
PATHERR or RESVERR messages (as the result of policy 
based—admission control failure, to Oprenge a reason for 
rejecting the request). 


Since an LPMs return POLICY_DECISION is an array, an LPM can accept a subset 
of flows in FlowDescList and reject the rest of them, if appropriate. For example, since 
FF style RESV messages can contain multiple flows, when an LPM rejects some 
flows and accepts others, the SBM generates a separate RESVERR message for 
each rejected flow; before sending the RESVERR message, PCM calls each LPM to 
supply policy data objects for each outgoing RESVERR message. 


Reserved 
[out] Reserved for future use. 


Return Values 


LPM_RESULT_READY 
The LPM has made a policy decision. The result is available in LpmPriortyValue. 


LPM_RESULT_DEFER 
The LPM was unable to return a decision immediately, but will do so using the © 
callback function cbpAdmitRsvpMsg. The LPM must call the callback within the time 
period specified by the ResultTimeLimit parameter of LPM_Initialize, otherwise the 
PCM will assume LPV_REJECT. , 


Any othervalue sy | 
The PCM assumes LPV_DONT_CARE. In addition, the PCM will assume the return 
value to be synchronous, and thus will not expect the LPM to call the | 
cbpAdmitRsvpMsg callback function; even if the LPM calls the function later, the 
result will be rejected. : 7 
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Remarks 


The Subnet Bandwidth Manager (SBM) forwards RSVP PATH, RESV, PATHERR, 
RESVERR, PATH_TEAR, and RESV_TEAR messages to the PCM. If a request passes 
LPM policy-based admission (in which case the success status is passed up through the 
PCM to the SBM), the SBM performs resource based—admission control as part of its 
RSVP processing; if resource based—admission control fails, the SBM will instruct the 
PCM to instruct each LPM to delete its state through the LPM_CommitResv function. In 
such circumstances, the SBM (and not the LPMs) will create the requisite RSVP error 


message. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 


LPM CommitResv 


~The LPM_CommitResv function is called by the PCM to obtain reservation commitment 
decisions from the LPM. 


Parameters : 


RsvpSession a 
[in] Pointer to the RSVP session object for which the reservation commitment is being 
requested. 


Flow!nstalledintf 
[in] Pointer to the interface on which the message was received. The received 
interface IP address is supplied as the RSVP HOP object, and the Logical Interface 
Handle is set to the SNMP Index. Note that interface index numbers can change with 
the addition and deletion of interfaces, due to the Plug and Play features of 
Windows 2000. 


RsvpStyle 
: [in] RSVP reservation style being requested. 
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FilterSpecCount 
[in] Number of filter specs in ppFilterSpecList. 


ppFilterSpecList 
[in] Array of filter specs, listing the senders for whom the flow is created. 


pMergedFlowSpec 
[in] Flow spec installed on the specified interface. The flow spec is a merged flow for 
all receivers that can be reached | Flow!nstalledinit. 


CommitDecision 
[in] Value of the commitment decision reached by the LPM. The following list indicates 
possible values: 


RESOURCES_ALLOCATED 
RESOURCES_MODIFIED 


Remarks 

When the resources are allocated by the SBM for a new reservation, it calls LPMs with 
CommitDecision set to RESOURCES_ALLOCATED. When resources allocated for an 
existing reservation are changed, the SBM calls the LPM _CommitResv function with 

- CommitDecision set to RESOURCES_MODIFIED. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 


LPM Deinitialize 


The LPM_Deinitialize function allows the PCM to instruct LPMs to deinitialize, whether 
due to system shutdown or a change in Designated Subnet Bandwidth Manager (DSBM) 
status. This occurs when the Admission Control Service no longer needs to do policy 
_based-—admission control, such as when a demotion from DSBM status occurs. LPMs 
should free resources, close connections to external entities such as policy servers, 
directory services, and perform any other cleanup necessary to properly relinquish LPM 
activities. The PCM will unload the DLL after LPM_Deinitialize returns. 


Parameters 


LomHandle 
ce handle to the LPM, as supplied through LPM_Initialize during initialization. 
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Return Values 


LPM_OK 
The LPM deinitialized successfully. 


lf another value is returned from LPM_Deinitialize, the PCM will record the name of this 
DLL (implementations of LPMs are always in the form of a DLL), as well as this return 
value, in the Event Log. 


Remarks 
LPMs do not need to return errors for outstanding requests when LPM_Deinitialize is 
called; PCM assumes LPV_REJECT for outstanding requests. LPMs should deinitialize 
synchronously before returning. If an LPM has been loaded and initialized multiple times 
to facilitate the handling of multiple PE types, the PCM will call LPM_Deinitialize 


- multiple times as well. 


es 


Windows NT/2000: Requires Windows 2000. 


Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 


LPM DeleteState 


The LPM_DeleteState function is called by the PCM to delete LPMs’ RSVP state 
information. RSVP states are deleted on various occasions, including when the SBM 
receives RSVP TEAR/ERR messages, or when an RSVP state times out. The | 
LPM_DeleteState function call is synchronous. The PCM does not expect any results 


from the LPM for this request. 


PES 
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Parameters 

RsvpSession 
[in] Pointer to the RSVP session object for which the LPM should delete its state. This 
value is never NULL. 


ReceivedintfAddress | 
[in] Pointer to the interface on which the RSVP TEAR message was received. The 
received interface IP address is supplied as the RSVP HOP object, and the Logical 
Interface Handle is set to the SNMP Index. If the PCM is calling the LPM_DeleteState 
function for any reason other than an RSVP TEAR message, this argument can be 
NULL. Note that interface index numbers can change with the addition and deletion of 
interfaces, due to the Plug and Play features of Windows 2000. | 

RsvpMsgType 
[in] RSVP message type for which the LPM should delete its state. 

RsvpHop 7 
[in] Pointer to an RSVP HOP object identifying the node that sent the TEAR message. 

| LPMs can use this argument to locate state information. 
-RsvpStyle 

[in] Pointer to an argument that specifies the RSVP reservation style for RSVP 

RESV_TEAR messages. LPMs can use this argument to locate state information. 


FilterSpecCount 
[in] Specifies the number of FilterSpecs in FilterSpecList. For RESV messages, 
FilterSpecCount is dependent on RsvpStyle. For PATH messages, this value will 
always be 1. 


FilterSpecList 
[in] Array of FilterSpec pointers. Note that the contents of FilterSpecList i is dependent 
on RAsvpStyle; if RsvoMsgType is RSVP_PATH then FilterSpecList specifies the 
SenderTemplate, if RsvpMsgType is RSVP_RESV then Bue Des is the list of 
filters for which the RESV state needs to be deleted. 
DeleteReason 
[in] Reason for deleting the state. Possible values are: 
RCVD_PATH_TEAR 
RCVD_RESV_TEAR 
ADM_CTRL_FAILED 
STATE_TIMEOUT 
FLOW_DURATION 


LPMs can use Re elena On for statistic gathering or any other use. 


Remarks | : 

The PCM will call the LPM_DeleteState function for each LPM: LPMs should be 
prepared to handle LPM_DeleteState for a nonexistent state, as described further in the 
Remarks section of the ere nee function. | 
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Windows 2000. 


Unsupported. 


Declared in Lpmapi.h. 
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Windows NT/2000 
Windows 95/98 
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[in] Pointer to the interface on which the RSVP message will be sent out. The sending 


interface IP address is supplied as the RSVP HOP object, which equates to PHOP for 


PATH messages and NHOP for RESV messages. The Logical Interface Handle is set 
to the SNMP Index. Note that interface index numbers can change with the add 
and deletion of interfaces, due to the Plug and Play features of Windows 2000. 


ri] 


ition 


pRsvpMsgO 


bjs 
[in] RSVP objects generated by the SBM 


following objects are supplied. 


in host order. The 


ts are 


jec 


All RSVP ob 


Value 


RsvpMsgType 
RsvpSession 


RsvpHop 


RsvpStyle 


RsvpScope 


FlowDescCount 
FlowDescList 


pRsvpObjectsCount 
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Meaning 


RSVP message type, as defined in the RSVP protocol. This can 
be used by an LPM to locate the state from which it can 
generate policy data objects. 

RSVP session for which the SBM requires policy information. 
This can be used by an LPM to locate the state from which it 
can generate policy data objects. _ 

The HOP to which the RSVP message is being forwarded. 

Since a PATH message is sent directory to the session address, 
this HOP pointer is NULL for PATH messages. For all other 
messages, the address in the HOP object is the node address 


and the LIH is unused. 


RSVP reservation style, as defined in the RSVP protocol. If an 


_RESV message is being sent out by the SBM, AsvpSiyle 


specifies the reservation style. If a PATH message is being 

sent, RsvpStyle is NULL. | 

The RSVP scope of an outgoing RESV message, as long as the 
SCOPE object is not NULL. Used only for WF-style 

reservations. For all other RSVP reservation styles, RsvpScope 
is NULL. 

Number of flow descriptors. 

Array of flow descriptor pointers in the outgoing RSVP 

message. For PATH messages, there will be only one 
FlowDescriptor containing sender template and sender TSPEC. 


[out] Pointer to the number of policy objects being returned. When an LPM is 
immediately returning results, the pRsvpObjectsCount and pppRsvpObjects © 
parameters should be used to return policy data objects. Note that the buffer 
containing the policy data objects should be allocated using the memory allocation 
function PALLOCMEM, ee within the LPM_Initialize function. 


-pppRsvpObjects 


[out] Pointer to an array of policy data object pointers returned in response to the | 
request. Note that the buffer containing the policy data objects, and this array of policy 
data object pointers, should be allocated using the memory allocation function 
PALLOCMEM, supplied within the LPM _Initialize function. 


Reserved 


_ [out] Reserved for future use. 


Return Values 


LPM_RESULT_READY 


~The LPM has returned the policy data using fi patel nai pppevpObjects 


parameters. 
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LPM_RESULT_DEFER 
The LPM is unable to return the policy data objects synchronously, and will return the 
policy data objects with a subsequent call to cbpGetRsvpObjects. 


LPM_DROP_MSG | | 
The LPM can return this value when it does not want to refresh the outgoing 
message. | 


LPM_ERROR | 
The LPM has encountered an error. 


Remarks 

If an LPM doesn’t have policy data to return from the LPM_GetRsvpObjects function 
call, it should synchronously return LPM_RESULT_READY, set pppRsvpObjects to 
NULL, and set pRsvpObjectsCount to zero. If a synchronous return isn’t possible, an 
LPM should return LPM_RESULT_DEFER, and return the result by calling the 
cbpGetRsvpObjects callback function. If the LPM does not have any policy data objects 
to return, it can set pppRsvpObjects to NULL and pRsvpObjectsCount to zero. 


If any LPM returns LPV_DROP_MSG, the SBM will not send out an RSVP refresh 
message, and will free the policy data objects returned by other LPMs (those that did not 
return LPM_DROP_MSG, if any). By not sending out RSVP refresh messages, a flow’s 
RSVP state both upstream and downstream will begin to age, and eventually get 
deleted. 


Note The SBM will send out the RSVP refresh message even if some or all LPMs fail to 
return policy data objects in a timely fashion, even though such an outgoing RSVP 
message may not contain all policy data objects it should. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 


LPM Initialize 


The LPM_Initialize function initializes a local policy module (LPM). This occurs when the 
Admission Control Service needs to do policy based—admission control, such as when 
an SBM becomes the Designated Subnet Bandwidth Manager (DSBM). LPMs should 
initialize themselves, synchronously, before returning. 
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ee 


Parameters 
LpmHandle 
_ [in] Unique handle for the LPM, assigned by the PCM. 


ResultTimeLimit 
[in] Represents the value, in seconds, within which the LPM must respond to PCM 


requests. An LPM’s failure to respond to PCM requests within ResultTimeLimit results 
in assumed rejection of the PCM request. The PCM will ignore responses provided 
after ResultTimeLimit. 


MemoryAllocator 
[in] PCM provided—memory allocation routine PALLOCMEM. This function call must 


be used by LPMs when returning policy information to the PCM. This function, 
combined with the PFREEMEM function, allows the SBM to use different memory 
management schemes without requiring the recompilation of LPMs. Its use is — | 
recommended. LPMs do not need to use this function to manage their local buffers. 


FreeMemory 
[in] PCM provided—memory freeing routine PFREEMEM. This function, combined with 


the function PALLOCME\M, allows the SBM to use different memory-management 
schemes without requiring the recompilation of LPMs. Its use is recommended. If 
memory allocated with MemoryAllocator is not returned to PCM, nor freed with this 
call, a memory leak will result. LPMs do not need to use this function to manage their 
local buffers. The SBM will free this buffer when it is no longer needed. This function 
call must be used by LPMs when returning policy information to the PCM. 


cbpAdmitRsvpMsg =: | 
[in] Pointer to the function used to asynchronously return results to the 


LPM_AdmitRsvpMsg request. 

cbpGetRsvpObjects | | | 
in] Pointer to the function used to asynchronously return policy data objects from calls 
to the LPM_GetRsvpObjects request. A | 
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ConfiguredLpmCount 
[in] Number of LPMs configured for use with the PCM. Note that this value does not 
indicate whether LPMs have been successfully loaded or initialized. This value is a 
useful indication that the PCM will attempt to load multiple LPMs on the system. 


SupportedPeType 
[out] Valid Policy Element (PE) type that the LPM uses to make policy based— 
admission control decisions. Each LPM can only support one PE type, though future 
versions may allow an LPM to support multiple PE types. Reserved PE hes are 
defined in Lpmapi.h. 


It is possible for a single DLL to support multiple PE types by having the DLL name 
entered multiple times in the PCM configuration data. Under such circumstances, the 
PCM will load and call the same LPM_Initialize routine multiple times; it is the LPM’s 
responsibility to return different PE types for these additional calls. 


LPMs can return a special PE type, LPM_ALL_PE_TYPES, to indicate that it will 
make policy based—admission control decisions based on all policy data objects. In 
this scenario, the PCM will assume that this LPM understands how to generate policy 
data objects for outgoing messages that the PCM is not able to understand. 


Reserved 
[in, out] Reserved for future use. 


Return Values 


If the LPM is initialized successfully, and a valid PE type is returned in 
SupportedPeType, the return value will be LPM_OK. The PCM treats any value other 
than LPM_OK as an error, and unloads the DLL (LPMs are always implemented as 
DLLs). If a value other than LPM_OK is returned or SupportedPeType is invalid, the 
PCM writes a record to the Event Log and includes the name of the DLL and the 
returned error value. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
_ Header: Declared in Lpmapi.h. 


Lpm_IpAddressTable 


The Lpm_IpAddressTable function is used by the PCM to pass a list of IP addresses 
assigned to the Windows 2000 Server upon which the LPM is initialized. The PCM calls 
this routine after the LPM has successfully initialized, but before making any requests. 
The PCM also uses the Lpm_IpAddressTable function to update LPMs regarding IP 
address changes. LPMs are expected to detect IP address changes and update their 


_ states appropriately. 
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Parameters 


clpAdadrTable 
[in] Number of addresses in the IP table. 


plpAdadrTable 


[in] Pointer to an LPMIPTABLE structure that contains the IP addresses assigned to 
the Windows 2000 Server on which the LPM resides. 


_ 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lomapi.h. 


LPM Structures 


The following structures are exposed by the Microsoft-provided LPM: 


¢ LPMIPTABLE 
° PALLOCMEM 
e PFREEMEM 


LPMIPTABLE ~ | 


The LPMIPTABLE structure contains IP information, including the SNMP index, IP 


address, and subnet mask for each interface. The LPMIPTABLE structure is supplied as 
an argument for the LPM_IpAddressTable function. 


Members 


Ullfindex 
SNMP index for the interface. | 


IflpAddr me 
IP address for the interface. 
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lfNetMask 
IP subnet mask for the interface. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lomapi.h. 


PALLOCMEM 


The PALLOCMEM function is a memory allocation function provided by the PCM, used 
for allocating memory when returning policy information to the PCM. The PALLOCMEM 
function is supplied as a parameter of the LPM_Initialize function, and allows the SBM 


to experiment with different memory-management schemes without requiring 
recompilation of LPMs. 


Parameters 


Size 
Size of the memory buffer required by the LPM. 


Remarks 
LPMs do not need to use this function to manage their local buffers. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 


PFREEMEM 


The PFREEMEM function is a memory-freeing function provided by the PCM. 
PFREEMEM frees memory buffers that were allocated using PALLOCMEM. The 
PFREEMEM function is supplied as a parameter of the LPM_Initialize function. The 
combination of PALLOCMEM and PFREEMEM allows the SBM to experiment with 
different memory-management schemes without requiring recompilation of LPMs. 
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Parameters 


pv 
Pointer to the memory buffer to free. 


Remarks 


LPMs do not need to use this function to manage their local buffers. LPMs need to use 
this function to free buffers that were allocated, but were not sent to the PCM. For — 
example, if a buffer is allocated in anticipation of a PCM’s response to a request, but a 
response is never returned (perhaps the remote policy store is unavailable or 
unresponsive), that buffer must be freed with this function, or a memory leak will ensue. 


Windows NT/2000: Requires Windows 2000. 
Windows 95/98: Unsupported. 
Header: Declared in Lpmapi.h. 
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INDEX 


Networking Services Programming Elements — 
Alphabetical Listing — 


This final part, found in each volume in the Networking Services Library, provides a 
comprehensive programming element index that has been designed to make your life 
easier. | 


Rather than cluttering the TOCs of each individual “olunie in this library with the names 
of programming elements, I've relegated such per-element information to a central 

location: the back of each volume. This index points you to the volume that has the 
information you need, and organizes the information in a way that lends itself to easy 
use. 


Also, to Keep you as informed and up-to-date as possible about Microsoft technologies, 
I've created (and maintain) a live Web-based document that maps Microsoft 
technologies to the locations where you can get more information about them. The 
following link gets you to the live index of technologies: 


www.iseminger.com/winprs/technologies 


The format of this index is in a constant state of improvement. I've designed it to be as 
useful as possible, but the real test comes when you put it to use. If you can think of 
ways to make improvements, send me feedback at winprs @ microsoft.com. While | can't 
guarantee a reply, I'll read the input, and if others can pelent | will ere the idea 
into future libraries. 


Locators are arranged by Volume Number followed by Page Number. 
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